feat(Periscope): add classified event authoring

[kyleve]

Posted by an AI agent on kve's behalf.

Summary

• add @LogScope, @LogEvent, and @LogField authoring with compiler-checked classified inputs
• add stable event names, field keys, event versions, and provider-neutral JSONValue payloads
• make Log scope-typed and add type-erased LogContext propagation
• migrate Periscope built-in events and preserve the optional SwiftUI context accumulator
• add the host macro suite, test-runner support, and correct SwiftSyntax attribution
• retain transitional legacy event APIs for the app migration in refactor(Logging): migrate app events to classified logging #269

Problem

The former model used enum event families and hand-written remote projections. Emission sites did not prove the exposure, semantic kind, or Swift type.

Architecture

@LogScope defines a stable scope namespace. Each nested @LogEvent struct defines one stable event name and version. Each @LogField supplies a stable coding key, exposure, and semantic kind.

Generated event methods accept phantom-typed ClassifiedLogInput values. Local records retain the complete event. The generated classifiedFields projection contains approved values and restricted descriptors without restricted values.

Log<Scope> retains scope derivation, entity scopes, linking, tags, freeform helpers, task-local context, and spans. LogContext carries the same recorder state without a generic scope.

Design decisions

• Stable scope, event, and field identifiers use explicit string literals.
• JSONValue encodes natural recursive JSON and rejects non-finite doubles.
• Category fields require closed, string-backed CaseIterable values.
• LogScopeDefinition is Sendable for safe span isolation.
• SwiftSyntax is pinned at 603.0.2 for the host macro target.
• Attribution classifies SwiftSyntax as a development tool, not a shipped library.

Privacy boundary

A shareable field requires approval at declaration and emission. This approval does not inspect the contents of strings or JSON values.

Local sinks can access the complete event. The classified projection is the safe baseline export surface, not a security boundary for arbitrary sinks.

Breaking changes

• Periscope built-in event names and payload shapes use the new stable wire format.
• Typed task contexts and instance contexts now use scope definitions.
• Old span rows cannot pair with the new span event name.

This PR keeps the legacy remote-field interfaces temporarily. PR #269 removes them after it migrates all app events.

Compatibility

There is no store migration or decode fallback. Old rows remain as raw historical records with their stored message and payload.

The development Periscope store must be removed before new-build validation. This repository is pre-release, so the old-span limitation is accepted.

Review focus

• macro diagnostics, stable coding keys, and generated method signatures
• classified input type enforcement and category membership checks
• restricted descriptors that never contain raw values
• scope-typed context propagation and the optional SwiftUI accumulator
• host macro test execution on a clean checkout
• attribution reachability at macro targets

Testing

• ./swiftformat --lint
• ./test PeriscopeMacrosTests — 15 architecture tests and 10 macro tests passed
• ./test PeriscopeMacrosTests — no architecture violations and all host regressions passed
• ./test --skip-architecture PeriscopeCoreTests — 317 tests passed

Stack

This PR is 1 of 2 and targets main. PR #269 migrates app-level logging and removes the transitional APIs.

[kyleve]

(important) Is this useful to keep at all if the macro gives us access to the JSON and we can format it on ask?

[kyleve]

IMO not useful, let's remove and just use the full type qualification.

[kyleve]

I don't think this should be restricted, it's not PII or otherwise identifiable?