[AAASM-5750] ✨ (gateway): Forward the hook-layer audit event to the runtime

[Chisanan232]

Target

• Task summary:

  createNativeGatewayClient's record / recordResult / scanPrompts constructed the audit event, handed it over, and dropped it — firing only a one-time AA_DEBUG note. They now send it on nativeClient.sendEvent, the same primitive and the same connected session that already carries the boot registration event (init-assembly.ts:831), so a governed tool call — allowed or denied — reaches the runtime's audit pipeline.

• Task tickets:

  • Task ID: AAASM-5750.
  • Relative task IDs:
    • AAASM-5681 — measured the drop and declared it; never built a sink.
    • AAASM-4847 — the superseded "there is nowhere for these to go" note.
  • Relative PRs:
    • Siblings, same capability: python-sdk Bump napi-derive from 3.5.10 to 3.6.0 in /native/aa-ffi-node #319, go-sdk [AAASM-2774] 🔧 (sonar): Wire projectVersion off 0.0.0 + cover in release skills #203.

• Key point change (optional):

  Design, and the code that decided it. The AAASM-4847 comment said hook-layer events "have nowhere to go". That was true of the gateway wire — there is still no HTTP audit route for the SDK to POST to — and false of the runtime channel, which was already open and already carrying an event. native/aa-ffi-node/src/lib.rs:152 (send_event → AssemblyClient::report_event) reaches the runtime pipeline, which enriches, re-scans and admits the frame to its audit pipeline.

  auditSink is computed, not fixed. createNativeGatewayClient is also handed the fallback stub createNativeClient returns when the native binding cannot be loaded, whose sendEvent is a no-op. Declaring "forwarded" there would be a claim about a channel the client does not hold, so the value keys off canRegister — which is exactly "the binding loaded", the same fact the record path depends on.

  §6 term earned. napi-inprocess over a loaded binding → Observed (forwarded). The no-op client (auto / sdk-only / grpc-sidecar) holds no transport at all → discarded → Unsupported; that gap is structural, not unwired. A native client over the fallback stub → discarded → Degraded.

  Not changed: no redaction is attempted on this side — the runtime's scanner is the unconditional gate on every inbound frame, and a weaker copy here would only invite the two to disagree.

Effecting Scope

• Action Types:
  • ✨ Adding new something
    • 🟢 No breaking change
  • ✏️ Modifying existing something
    • 🟢 No breaking change
• Scopes:
  • 🧩 SDK public API
  • 🪡 API client and transport
  • 🫀 Data model and types
  • 🧪 Testing
    • 🧪 Unit testing
  • 📚 Documentation
• Additional description:
  AuditSinkDisposition gains "forwarded". The union is a public export, so a consumer exhaustively switching on it must add a branch; the two existing values keep their meanings.

Description

• src/types/gateway-governance.ts — add "forwarded"; map each value onto the §6 term it earns.
• src/gateway/client.ts — send the three audit methods over sendEvent; compute auditSink from canRegister; add stringifyForAudit so a circular or BigInt tool result degrades to a lossy record rather than throwing out of the sink into the governed call.
• src/core/init-assembly.ts — the warning fires for "discarded" only, and says what to do about it.
• Tests, docs, and every remaining prose claim that both shipped clients drop the event.

Validation

pnpm typecheck, pnpm lint (0 issues), pnpm test (730 passed, 2 skipped, 73 files), pnpm build — all green.

Downstream-boundary stub with a reachability control (AC2). tests/audit-sink-disposition.test.ts's boundary() is the NativeClient seam, not a stand-in for the code under test. The positive control asserts a queryPolicy crossing; the finding asserts three distinct sendEvent crossings carrying three distinct payloads. A new case drives a real deny through withAssembly — the shipped interceptor, no injected sink — and asserts the deny reason crosses the same boundary.

Proven able to fail (AC3). Reverting the three sinks to async () => undefined:

1. a client declaring "forwarded" reaches the boundary with every audit method
   AssertionError: expected [] to have a length of 3 but got +0
2. a governed tool call through withAssembly forwards the deny to the boundary
   AssertionError: expected false to be true
3. sends all three audit methods to the native event channel
   AssertionError: expected [] to deeply equal [ 'tool_call_audit', …(2) ]
4. does not let a non-serializable tool result fail the audit call
   AssertionError: expected "vi.fn()" to be called 1 times, but got 0 times

Quote lockstep is load-bearing. Rewording docs/02-quick-start/index.md alone, leaving quote= untouched, reddens no sentence is unbound and unallowed and … matches exactly one whole sentence.

tests/napi-audit-noop.test.ts is kept rather than deleted: it now asserts the inversion of what it used to demand, so a revert to the no-op reddens the exact file that once required it and the AA_DEBUG note cannot quietly return.

Known behaviour worth a reviewer's eye

nativeClient.sendEvent never throws — the transport stashes a failure and surfaces it on the next queryPolicy. That is what makes these safe to call from the hook layer, but it means a broken IPC channel can deny a later call under enforce. That is the correct fail-closed reading of an unreachable runtime rather than an audit-driven enforcement change, and it is pre-existing behaviour that registration already had.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XWLmA8FgULT9e6ntdCo1H2

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Chisanan232]

Second sweep — the first one's method was wrong, and it missed five sites.

The first pass enumerated by phrase. An independent audit against what each sentence asserts found five more, committed in 1cf65202b:

• src/types/assembly-context.ts:21-25 — the per-framework §6 note still said the callback handler reaches Observed "only when the gateway client actually persists what it records, which the default no-op client and the napi-inprocess client both do not". The napi client now does.
• docs/04-guides/index.md:164 and its ** footnote at :175-177 — the capability table told the reader a sink is caller-supplied-only. The two had to move together; correcting the footnote alone would have left the row pointing at it.
• tests/quickstart-negative-control.test.ts:265-269 — a scope comment asserting a deny is Unmeasured on the shipped path.
• tests/quickstart-claim-bindings.test.ts:154 — the binding id was allow-event-is-discarded-not-retained, i.e. the gate reported under a label asserting the opposite of the quote two lines below it, which had already been corrected.

Two residuals I looked at and deliberately did not change:

1. tests/napi-audit-noop.test.ts — the filename still asserts the sinks are no-ops. The header supersedes it explicitly, every assertion in the file is the inversion, and tests/audit-sink-disposition.test.ts:53 refers to it by that name. Renaming is cosmetic and would touch a cross-reference; happy to do it if a reviewer prefers.
2. dist/** carries compiled copies of the src/ docstrings and is untracked build output — it corrects itself on the next build.

Also in 1cf65202b: codecov/patch was red at 76.92% against a 93.5% target. The uncovered lines were both sides of each optional field in the audit payloads and the JSON.stringify(...) ?? String(...) branch. Those are real wire-shape decisions rather than coverage padding — a spread that always fires and one that never fires are indistinguishable if only one side is driven, and JSON.stringify returning undefined (a function, a symbol, undefined itself) would otherwise put a recorded outcome on the wire as a missing field. src/gateway/client.ts is now 100% statements / 97.5% branches; the one remaining uncovered branch (:79) predates this PR.

[Chisanan232]

Review round 2 — regression fixed, Observed withdrawn. Head 7b4d68cf0.

1. The regression, fixed first. stringifyForAudit fell back to String(value), and String() throws too — an Object.create(null) object has no Symbol.toPrimitive / valueOf / toString, and querystring.parse() returns exactly those. Confirmed both conversions throw, then reproduced the review's matched control against built output:

BEFORE   native client, circular null-prototype:  REJECTED -> TypeError: Cannot convert object to primitive value
         no-op  client, same input:               ok            <- control

AFTER    native client, circular null-prototype:  ok
         no-op  client, same input:               ok            <- control

The second conversion now has its own guard and falls back to "[unserializable]". The new case asserts as a precondition that both JSON.stringify and String throw on the input, so it cannot pass over a value that was never dangerous.

2. Observed withdrawn — seven sites. You were right that gateway-governance.ts:32-33 was the sharpest: "This SDK observes that the event crossed the boundary" is false as written. sendEvent returns void, is fire-and-forget, and never throws — the transport stashes failures for a later queryPolicy — so a client whose connect always rejects still reports forwarded. Every site now claims the handoff and nothing past it, and the type doc says up front that no value here earns §6 Observed.

I did not substitute a different §6 term. The honest position is that this layer makes no §6 recording claim at all; the enforcement claims (Evaluated / Denied before execution) are untouched. I have not referenced the durability defect by ticket since you are filing it — say the word and I will add the reference.

3. The Degraded row is gone. Verified your call graph: napi-inprocess throws on a binding load failure (createNativeClient → loadNativeBinding), and every other mode returns the no-op client without reaching createNativeGatewayClient. So the stub can never arrive there via initAssembly. Reduced to Observed-free forwarded / discarded(Unsupported), and the discarded arm is now documented as reachable only by a caller constructing the exported factory directly — which is true, and is why the guard stays.

4. The referent gate discriminated nothing — fixed and proven. Your mutation reproduced exactly: scan() → return; left all 5 green. Threaded a file count out of the walk and pinned a file that only exists in this repo. Re-running the same mutation now:

MUTATION scan() returns immediately:  PASS (5)  FAIL (1)
  1. the WALK reaches this repository's files — not just the detector

5. Count corrected. The suite is 740 (738 passed, 2 skipped) at this head — the 730 in the body was stale before I added tests, and 732 was your reading of the same stale moment. src/gateway/client.ts holds 100% statements / 97.5% branches; the one uncovered branch (:79) predates this PR.

Gates: typecheck, lint, test, build, test:coverage all green.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud