[zac]

Makes @BuiltInCodeMode actually remove code, and sets the template the other 14 bridge families will copy. EventKit (calendar and reminders) is the pilot.

Why

The macro generated typed Arguments decoding, and then 109 of ~117 tools threw it away: they passed arguments.raw to a bridge that parsed every argument again by string key. Every argument was declared twice, defaults lived in both hint prose and code, and the results were hand-built JSONValue described by an unchecked sentence. Models saw every helper as Promise<CodeModeValue>.

What a tool author writes now

@BuiltInCodeMode(.calendarRead, path: "apple.calendar.listEvents")
struct CalendarListEventsTool: BuiltInCodeModeTool {
    struct Arguments: Sendable {
        @ToolParam("Range start; now when omitted.")
        var start: Date?                 // decoded and validated by the macro
        @ToolParam("Max number of items.")
        var limit: Int = 50              // hint gains "Default: 50."
        …
    }

    func call(arguments: Arguments, context: BridgeInvocationContext) throws -> [CalendarEvent] {
        …                                // the logic, not a forward to a bridge
    }
}

@ToolResult struct CalendarEvent {     // encoder + schema from one declaration
    var identifier: String
    @ToolField("ISO 8601 timestamp") var startDate: Date
    …
}

And what the model sees:

listEvents(args?: { start?: string; limit?: number; … }): Promise<Array<{
  identifier: string;
  /** ISO 8601 timestamp */
  startDate: string;
  …
}>>;

Commits

• Permissions (4f9f4f6). One implementation of the broker sequence, used by the registry. Tools gain argumentDependentPermissions(for:) for permissions that depend on the call (location read in current mode). An audit found all 29 static declarations correct.
• Typed EventKit arguments (651e054). Macro defaults as initializers (var limit: Int = 50), Date properties, bridges take typed input.
• codeModeTitle removed (5b2e90f). 120 titles no model ever saw; derived from the path instead.
• One tool per helper, Patch<T>, logic in call (b516c56).
  • createEvent/updateEvent and createReminder/updateReminder/completeReminder were aliases on one tool, disambiguated by hand-written JS that injected an operation argument. Now separate tools with correct required arguments. Several tools share one CapabilityID, so the registry keeps a list per ID and dispatch passes the called name through (to the handler and to error suggestions).
  • Scripts could never clear a field: the registry rejected null before any handler ran. Patch<T> (missing / null / value) makes clearing real on update tools, advertised as T | null only where it's true. The macro generates hasChanges(_:) so an empty update is rejected without a hand-kept field list.
  • EventKitBridge.swift is now 149 lines of shared helpers and result structs (544 on main).
• Typed results (a240d0c). @ToolResult structs, a runtime-derived CodeModeResultSchema with a compact public JSON form, and declarations that render it as the promise type. Unmigrated families keep -> JSONValue and their prose summary, so they compile unchanged.
• Docs: PLAN-typed-results.md, PLAN-async-bridges.md (the async decision, for the next branch), README install snippet fixed for the existing tags.

For the reviewer

• Behaviour changes scripts can see, all intended:
  • null now clears a field on the update helpers: notes, location, url and isAllDay on updateEvent; dueDate, notes, isCompleted, priority and the calendar on updateReminder. Before, it was rejected.
  • createEvent with identifier, or updateEvent without one, is now an INVALID_ARGUMENTS error naming the right helper.
  • Write-date errors use the standard repairable date message instead of an EventKit-specific one.
  • Calendar create accepts a custom permission broker that reports .writeOnly for .calendarWriteOnly. The system broker already reported that case as granted.
• Public API changes: CapabilityRegistry.invoke(_:jsName:arguments:context:) gains an optional jsName; CapabilityDescriptor and JavaScriptAPIReference gain nullableArguments and resultSchema (both decode with defaults, so earlier encodings still load); a host registration now replaces every built-in registration whose JS names it overlaps, or the whole capability when it names none.
• The JSON results scripts receive are unchanged, including "" for absent strings. Whether those should become null is a deliberate decision left open in TODO.md.
• The registry change is the part most worth a close look: several registrations per CapabilityID, first-registration semantics for descriptor(for:)/registration(for:), and byCapability in search holding the first helper.
• Golden baseline: each diff is in the commit that caused it and is the intended review artifact.

Verification

Each commit was reviewed by an independent quality gate (Opus) until it passed; three rounds on the split, two on typed results. On the final head, locally:

• swift test: 356 + 12 + 32 tests passing
• scripts/check-typescript-declarations.sh: all 128 generated declarations compile under tsc --strict
• xcodebuild build for generic/platform=iOS and generic/platform=visionOS: clean

Not in this PR

Migrating the other 14 families (each with its hand-written globalThis.apple.* JS deleted), element types for argument arrays, named interfaces in the whole-surface declarations, and the async bridge work. All recorded in TODO.md and the two plan files.