@graphorin/core 0.6.1 → 0.7.0

package/dist/contracts/memory-store.d.ts

@@ -13,6 +13,19 @@ import { SessionScope } from "../types/session-scope.js";
  * pick its own physical layout (one big table, six tables, mixed) while
  * preserving append-only semantics - soft-delete only.
  *
+ * **Baseline vs full adapter (W-048).** This interface is the MINIMUM a
+ * third-party adapter must implement; `@graphorin/memory` accepts it and
+ * degrades gracefully (vector search, decay, consolidation, insights,
+ * graph expansion, conflict audit switch off where the surface is
+ * absent). Full feature parity with `@graphorin/store-sqlite` (asOf
+ * reads, vector KNN, decay signals, insights, entity graph, conflicts,
+ * consolidator state/DLQ) is described by `MemoryStoreAdapter` and the
+ * `*MemoryStoreExt` interfaces exported from the root of
+ * `@graphorin/memory`. Every Ext addition over the six tier namespaces
+ * is optional BY CONTRACT - a type test in `@graphorin/memory` pins
+ * `MemoryStore extends MemoryStoreAdapter`, so a core-only adapter can
+ * never stop compiling.
+ *
  * @stable
  */
 interface MemoryStore {
@@ -27,6 +40,28 @@ interface MemoryStore {
   /** Cleanly close any underlying handles. Idempotent. */
   close(): Promise<void>;
 }
+/**
+ * Maintenance extension over {@link MemoryStore} (W-066), mirroring
+ * the `SessionStoreExt` precedent: capabilities the sqlite adapter
+ * guarantees but a custom `MemoryStore` is not obliged to implement.
+ * The base contract is unchanged - existing implementations keep
+ * compiling.
+ *
+ * @stable
+ */
+interface MemoryStoreExt extends MemoryStore {
+  /**
+   * Delete `memory_history` rows older than the given AGE in
+   * milliseconds. The argument is an AGE (the implementation computes
+   * `cutoff = now - olderThanMs`), never an epoch cutoff - passing an
+   * epoch value would compute a nonsense cutoff far in the past and
+   * silently prune nothing. Returns the number of rows removed.
+   * History grows by design (every supersede / quarantine transition
+   * appends) and `purge()` already scrubs sensitive text; this is the
+   * storage-cost hygiene lever - nothing prunes automatically.
+   */
+  pruneHistory(olderThanMs: number): Promise<number>;
+}
 /** @stable */
 interface WorkingMemoryStore {
   list(scope: SessionScope): Promise<ReadonlyArray<Block>>;
@@ -67,6 +102,17 @@ interface SessionMemoryStore {
    * don't implement it fall back to `list` + fabricated ids on the export path.
    */
   listWithMetadata?(scope: SessionScope, opts?: SessionListOptions): Promise<ReadonlyArray<SessionMessageWithMetadata>>;
+  /**
+   * Full-text search over the scoped session messages.
+   *
+   * Query precedence (W-127): the POSITIONAL `query` parameter is
+   * authoritative; when the caller also sets `opts.query` (the field
+   * exists because {@link MemorySearchOptions} is shared with the
+   * option-object search surfaces), implementations MUST ignore it.
+   * The duplication is a known wart: narrowing `opts` to
+   * `Omit<MemorySearchOptions, 'query'>` is a candidate for the next
+   * major, not a change this line can make compatibly.
+   */
   search(scope: SessionScope, query: string, opts?: MemorySearchOptions): Promise<ReadonlyArray<MemoryHit>>;
 }
 /** @stable */
@@ -87,7 +133,18 @@ interface SemanticMemoryStore {
   remember(fact: Fact): Promise<void>;
   search(scope: SessionScope, opts: MemorySearchOptions): Promise<ReadonlyArray<MemoryHit<Fact>>>;
   supersede(oldId: string, newFact: Fact, reason?: string): Promise<void>;
-  forget(id: string, reason?: string): Promise<void>;
+  /**
+   * Soft-delete a fact. W-154: when `scope` is supplied, adapters that
+   * support tenant isolation MUST treat a fact outside the scope as a
+   * deterministic no-op (0 rows changed) - defense in depth so a
+   * leaked / cross-user id reaching a mutator cannot touch another
+   * user's memory. Omitting `scope` preserves the historical unscoped
+   * behaviour (trusted internal callers: consolidator, erasure
+   * cascades). The parameter is additive - existing adapter
+   * implementations with the narrower arity remain structurally
+   * compatible.
+   */
+  forget(id: string, reason?: string, scope?: SessionScope): Promise<void>;
 }
 /** @stable */
 interface ProceduralMemoryStore {
@@ -102,5 +159,5 @@ interface SharedMemoryStore {
   listFor(agentId: string): Promise<ReadonlyArray<MemoryRecord>>;
 }
 //#endregion
-export { EpisodicMemoryStore, MemoryStore, MessageRef, ProceduralMemoryStore, SemanticMemoryStore, SessionListOptions, SessionMemoryStore, SessionMessageWithMetadata, SharedMemoryStore, WorkingMemoryStore };
+export { EpisodicMemoryStore, MemoryStore, MemoryStoreExt, MessageRef, ProceduralMemoryStore, SemanticMemoryStore, SessionListOptions, SessionMemoryStore, SessionMessageWithMetadata, SharedMemoryStore, WorkingMemoryStore };
 //# sourceMappingURL=memory-store.d.ts.map

package/dist/contracts/memory-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-store.d.ts","names":[],"sources":["../../src/contracts/memory-store.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAuBA;;;;;;;;;AAWkB,UAXD,WAAA,CAWC;EAID,SAAA,OAAA,EAdG,kBAce;EACrB,SAAA,OAAA,EAdM,kBAcN;EAAqC,SAAA,QAAA,EAb9B,mBAa8B;EAAd,SAAA,QAAA,EAZhB,mBAYgB;EAAR,SAAA,UAAA,EAXN,qBAWM;EAChB,SAAA,MAAA,EAXM,iBAWN;EAAsC;EAAR,IAAA,EAAA,EARjC,OAQiC,CAAA,IAAA,CAAA;EAC3B;EAAqB,KAAA,EAAA,EAP1B,OAO0B,CAAA,IAAA,CAAA;;;AAC0B,UAJ9C,kBAAA,CAI8C;EAAO,IAAA,CAAA,KAAA,EAHxD,YAGwD,CAAA,EAHzC,OAGyC,CAHjC,aAGiC,CAHnB,KAGmB,CAAA,CAAA;EASrD,GAAA,CAAA,KAAA,EAXJ,YAWc,EAAA,KAAA,EAAA,MAAA,CAAA,EAXgB,OAWhB,CAXwB,KAWxB,GAAA,IAAA,CAAA;EAaV,MAAA,CAAA,KAAA,EAvBD,YAuBC,EAAA,KAA0B,EAvBN,KAuBM,CACvB,EAxByB,OAwBlB,CAAA,IAAA,CAAA;EAOV,MAAA,CAAA,KAAA,EA9BD,YA8BmB,EAAA,KAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EA9B4B,OA8B5B,CAAA,IAAA,CAAA;;;;;;;;AAE6B,UAvB/C,UAAA,CAuB+C;EAAR,SAAA,SAAA,EAAA,MAAA;EAM7C,SAAA,QAAA,EAAA,MAAA;EACA,SAAA,WAAA,EAAA,MAAA;;;;;;;;;AAMC,UAvBK,0BAAA,CAuBL;EAIK,SAAA,OAAA,EA1BG,OA0Be;EAQlB,SAAA,SAAA,EAAA,MAAmB;EACrB,SAAA,QAAA,EAAA,MAAA;EAAU,SAAA,SAAA,EAAA,MAAA;;;AAIY,UAhCpB,kBAAA,CAgCoB;EAAV,IAAA,CAAA,KAAA,EA/Bb,YA+Ba,EAAA,OAAA,EA/BU,OA+BV,CAAA,EA/BoB,OA+BpB,CA/B4B,UA+B5B,CAAA;EAAd,IAAA,CAAA,KAAA,EA9BC,YA8BD,EAAA,IAAA,CAAA,EA9BsB,kBA8BtB,CAAA,EA9B2C,OA8B3C,CA9BmD,aA8BnD,CA9BiE,OA8BjE,CAAA,CAAA;EAAR;;;;EAKY,gBAAA,EAAA,KAAmB,EA7BzB,YA6ByB,EAAA,IAAA,CAAA,EA5BzB,kBA4ByB,CAAA,EA3B/B,OA2B+B,CA3BvB,aA2BuB,CA3BT,0BA2BS,CAAA,CAAA;EACnB,MAAA,CAAA,KAAA,EA1BN,YA0BM,EAAA,KAAA,EAAA,MAAA,EAAA,IAAA,CAAA,EAxBN,mBAwBM,CAAA,EAvBZ,OAuBY,CAvBJ,aAuBI,CAvBU,SAuBV,CAAA,CAAA;;;AACmB,UApBnB,kBAAA,CAoBmB;EAAsD,SAAA,KAAA,CAAA,EAAA,MAAA;EAAV,SAAA,cAAA,CAAA,EAAA,MAAA;EAAd,SAAA,OAAA,CAAA,EAAA,MAAA;EAAR,SAAA,IAAA,CAAA,EAAA,QAAA,GAAA,MAAA,GAAA,WAAA,GAAA,MAAA;;;AAEnB,UAdtB,mBAAA,CAcsB;EAAO,GAAA,CAAA,OAAA,EAb/B,OAa+B,CAAA,EAbrB,OAaqB,CAAA,IAAA,CAAA;EAI7B,MAAA,CAAA,KAAA,EAfN,YAe2B,EAAA,IAAA,EAd5B,mBAc4B,CAAA,EAbjC,OAaiC,CAbzB,aAayB,CAbX,SAaW,CAbD,OAaC,CAAA,CAAA,CAAA;EAC1B,GAAA,CAAA,EAAA,EAAA,MAAA,CAAA,EAbO,OAaP,CAbe,OAaf,GAAA,IAAA,CAAA;;;AACuC,UAVlC,mBAAA,CAUkC;EAAd,QAAA,CAAA,IAAA,EATpB,IASoB,CAAA,EATb,OASa,CAAA,IAAA,CAAA;EAAR,MAAA,CAAA,KAAA,EARb,YAQa,EAAA,IAAA,EARO,mBAQP,CAAA,EAR6B,OAQ7B,CARqC,aAQrC,CARmD,SAQnD,CAR6D,IAQ7D,CAAA,CAAA,CAAA;EACU,SAAA,CAAA,KAAA,EAAA,MAAA,EAAA,OAAA,EARH,IAQG,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EARqB,OAQrB,CAAA,IAAA,CAAA;EAAO,MAAA,CAAA,EAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EAPP,OAOO,CAAA,IAAA,CAAA;AAI9C;;AAE6C,UAT5B,qBAAA,CAS4B;EACK,GAAA,CAAA,IAAA,EATtC,IASsC,CAAA,EAT/B,OAS+B,CAAA,IAAA,CAAA;EAAd,IAAA,CAAA,KAAA,EARtB,YAQsB,CAAA,EARP,OAQO,CARC,aAQD,CARe,IAQf,CAAA,CAAA;EAAR,MAAA,CAAA,EAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EAPW,OAOX,CAAA,IAAA,CAAA;;;UAHX,iBAAA;6CAC4B;6CACA;4BACjB,QAAQ,cAAc"}
+{"version":3,"file":"memory-store.d.ts","names":[],"sources":["../../src/contracts/memory-store.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAoCA;;;;;;;;;;AAuBA;AAeA;;;;;;;;;;;AAIgB,UA1CC,WAAA,CA0CD;EAA+C,SAAA,OAAA,EAzC3C,kBAyC2C;EAAO,SAAA,OAAA,EAxClD,kBAwCkD;EASrD,SAAA,QAAU,EAhDN,mBAgDM;EAaV,SAAA,QAAA,EA5DI,mBA4DsB;EAQ1B,SAAA,UAAA,EAnEM,qBAmEY;EACrB,SAAA,MAAA,EAnEK,iBAmEL;EAAuB;EAAkB,IAAA,EAAA,EAhE7C,OAgE6C,CAAA,IAAA,CAAA;EAAR;EACjC,KAAA,EAAA,EA/DH,OA+DG,CAAA,IAAA,CAAA;;;;;;;;;;;AAuBH,UA1EM,cAAA,SAAuB,WA0E7B,CAAA;EACgB;;;;AAI3B;AAQA;;;;;EAKqC,YAAA,CAAA,WAAA,EAAA,MAAA,CAAA,EAjFA,OAiFA,CAAA,MAAA,CAAA;;;AAAhC,UA7EY,kBAAA,CA6EZ;EACsB,IAAA,CAAA,KAAA,EA7Eb,YA6Ea,CAAA,EA7EE,OA6EF,CA7EU,aA6EV,CA7EwB,KA6ExB,CAAA,CAAA;EAAR,GAAA,CAAA,KAAA,EA5EN,YA4EM,EAAA,KAAA,EAAA,MAAA,CAAA,EA5EwB,OA4ExB,CA5EgC,KA4EhC,GAAA,IAAA,CAAA;EAAO,MAAA,CAAA,KAAA,EA3EV,YA2EU,EAAA,KAAA,EA3EW,KA2EX,CAAA,EA3EmB,OA2EnB,CAAA,IAAA,CAAA;EAIT,MAAA,CAAA,KAAA,EA9ED,YA8EoB,EAAA,KAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EA9E2B,OA8E3B,CAAA,IAAA,CAAA;;;;;;;;AAEsB,UAvEzC,UAAA,CAuEyC;EACtB,SAAA,SAAA,EAAA,MAAA;EAAwB,SAAA,QAAA,EAAA,MAAA;EAYd,SAAA,WAAA,EAAA,MAAA;;;AAI9C;;;;;;AAE6B,UA7EZ,0BAAA,CA6EY;EACU,SAAA,OAAA,EA7EnB,OA6EmB;EAAO,SAAA,SAAA,EAAA,MAAA;EAI7B,SAAA,QAAA,EAAA,MAAiB;EACW,SAAA,SAAA,EAAA,MAAA;;;AAET,UA7EnB,kBAAA,CA6EmB;EAAR,IAAA,CAAA,KAAA,EA5Ed,YA4Ec,EAAA,OAAA,EA5ES,OA4ET,CAAA,EA5EmB,OA4EnB,CA5E2B,UA4E3B,CAAA;EAAO,IAAA,CAAA,KAAA,EA3ErB,YA2EqB,EAAA,IAAA,CAAA,EA3EA,kBA2EA,CAAA,EA3EqB,OA2ErB,CA3E6B,aA2E7B,CA3E2C,OA2E3C,CAAA,CAAA;;;;;2BArExB,qBACA,qBACN,QAAQ,cAAc;;;;;;;;;;;;gBAahB,oCAEA,sBACN,QAAQ,cAAc;;;UAIV,kBAAA;;;;;;;UAQA,mBAAA;eACF,UAAU;gBAEd,oBACD,sBACL,QAAQ,cAAc,UAAU;mBAClB,QAAQ;;;UAIV,mBAAA;iBACA,OAAO;gBACR,oBAAoB,sBAAsB,QAAQ,cAAc,UAAU;oCACtD,wBAAwB;;;;;;;;;;;;8CAYd,eAAe;;;UAI5C,qBAAA;YACL,OAAO;cACL,eAAe,QAAQ,cAAc;uCACZ;;;UAItB,iBAAA;6CAC4B;6CACA;4BACjB,QAAQ,cAAc"}

package/dist/contracts/provider.d.ts

@@ -1,5 +1,6 @@
 import { Sensitivity } from "../types/sensitivity.js";
-import { Message } from "../types/message.js";
+import { ToolCall } from "../types/tool-call.js";
+import { Message, ReasoningContentMeta } from "../types/message.js";
 import { AISpan } from "./tracer.js";
 import { Usage } from "../types/usage.js";
 import { ReasoningContract, ReasoningRetention } from "./reasoning-retention.js";
@@ -132,11 +133,12 @@ interface ProviderRequestMetadata {
  */
 interface ProviderResponse {
   readonly text?: string;
-  readonly toolCalls?: ReadonlyArray<{
-    readonly toolCallId: string;
-    readonly toolName: string;
-    readonly args: unknown;
-  }>;
+  /**
+   * Tool invocations the model requested. W-127: reuses the canonical
+   * {@link ToolCall} (the inline shape here was structurally identical
+   * and only invited drift).
+   */
+  readonly toolCalls?: ReadonlyArray<ToolCall>;
   readonly usage: Usage;
   readonly finishReason: FinishReason;
   readonly providerMetadata?: Readonly<Record<string, unknown>>;
@@ -159,6 +161,18 @@ type ProviderEvent = {
 } | {
   readonly type: 'reasoning-delta';
   readonly delta: string;
+}
+/**
+ * Closes the current reasoning block (W-024). Deltas stay textual;
+ * this terminator carries the provider's opaque round-trip metadata
+ * (e.g. the Anthropic thinking-block `signature`, or `data` for a
+ * redacted block) so multi-step tool use with extended thinking can
+ * replay the block byte-equal on the next request. Adapters without
+ * per-block structure simply never emit it - consumers fall back to
+ * collapsing the deltas.
+ */ | {
+  readonly type: 'reasoning-end';
+  readonly meta?: ReasoningContentMeta;
 } | {
   readonly type: 'text-delta';
   readonly delta: string;

package/dist/contracts/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","names":[],"sources":["../../src/contracts/provider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAgBA;;;;;;;;AAYoB,UAZH,QAAA,CAYG;EAAkB,SAAA,IAAA,EAAA,MAAA;EAOQ,SAAA,OAAA,EAAA,MAAA;EAAd,SAAA,YAAA,EAhBP,oBAgBO;EAAa;EAQ5B,MAAA,CAAA,GAAA,EArBH,eAqBuB,CAAA,EArBL,aA0CD,CA1Ce,aA0CE,CAAA;EAgB/B;EAUA,QAAA,CAAA,GAAA,EAjED,eAiEgB,CAAA,EAjEE,OAiEF,CAjEU,gBAiEV,CAAA;EACG;EAAd,WAAA,EAAA,GAAA,EA/DD,eA+DC,CAAA,EA/DiB,OA+DjB,CAAA,MAAA,CAAA;EACY;;;;;EAOK,SAAA,kBAAA,CAAA,EAhEN,aAgEM,CAhEQ,WAgER,CAAA;;;;;;;AA0BrB,UAlFA,oBAAA,CAkFuB;EAavB,SAAA,SAAA,EAAgB,OAAA;EAEV,SAAA,WAAA,EAAA,OAAA;EAKL,SAAA,iBAAA,EAAA,OAAA;EACO,SAAA,UAAA,EAAA,OAAA;EACc,SAAA,gBAAA,EAAA,OAAA;EAAT,SAAA,SAAA,EAAA,OAAA;EAAQ;EAQ1B,SAAA,aAAY,EAAA,MAAA;EAcZ;EAC4C,SAAA,SAAA,EAAA,MAAA;EAUe;;;;;AAUvE;AAYA;AAOA;AAgBA;;EAGwB,SAAA,iBAAA,CAAA,EApKO,iBAoKP;;;;;;AA0BxB;AAWA;AAQA;AAeA;AAaA;;;;;UA7NiB,mBAAA;;;;;;;;;UAUA,eAAA;qBACI,cAAc;mBAChB,cAAc;wBACT;wBACA;;;;oBAIJ;6BACS,SAAS;yBACb;;;;;;;wBAAmB;sBAQtB;;;;;;;;;gCASU;;;;;;;UAQf,uBAAA;;;;;;;;;;;;UAaA,gBAAA;;uBAEM;;;;;kBAKL;yBACO;8BACK,SAAS;;;;;;;KAQ3B,YAAA;;;;;;;KAcA,aAAA;;qBAC4C;;;;;;;;;;;;;;;;;;;;;;iBAUe;;;;;;;yBAEjB;kBAA8B;;;kBACtC;;;;;;;UAO7B,gBAAA;;;;;;;;;;;UAYA,aAAA;iBACA;;;;;KAML,iBAAA;;;;;;;UAgBK,cAAA;;;wBAGO,SAAS;;;;;;;0BAOP,SAAS;;;;;;;;sBAQb,cAAc;;;;;;;;;;UAWnB,qBAAA;;;;;;;;;;KAWL,UAAA;;;;;;;;;UAQK,UAAA;;;wBAGO,SAAS;;;;;;;;;;;KAYrB,kBAAA,UAA4B,aAAa;;;;;;;;;;;;KAazC,yBAAA,iBACG,cAAc,wBACxB"}
+{"version":3,"file":"provider.d.ts","names":[],"sources":["../../src/contracts/provider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;AAiBA;;;;;;;;AAYoB,UAZH,QAAA,CAYG;EAAkB,SAAA,IAAA,EAAA,MAAA;EAOQ,SAAA,OAAA,EAAA,MAAA;EAAd,SAAA,YAAA,EAhBP,oBAgBO;EAAa;EAQ5B,MAAA,CAAA,GAAA,EArBH,eAqBuB,CAAA,EArBL,aA0CD,CA1Ce,aA0CE,CAAA;EAgB/B;EAUA,QAAA,CAAA,GAAA,EAjED,eAiEgB,CAAA,EAjEE,OAiEF,CAjEU,gBAiEV,CAAA;EACG;EAAd,WAAA,EAAA,GAAA,EA/DD,eA+DC,CAAA,EA/DiB,OA+DjB,CAAA,MAAA,CAAA;EACY;;;;;EAOK,SAAA,kBAAA,CAAA,EAhEN,aAgEM,CAhEQ,WAgER,CAAA;;;;;;;AA0BrB,UAlFA,oBAAA,CAkFuB;EAavB,SAAA,SAAA,EAAgB,OAAA;EAOI,SAAA,WAAA,EAAA,OAAA;EAAd,SAAA,iBAAA,EAAA,OAAA;EACL,SAAA,UAAA,EAAA,OAAA;EACO,SAAA,gBAAA,EAAA,OAAA;EACc,SAAA,SAAA,EAAA,OAAA;EAAT;EAAQ,SAAA,aAAA,EAAA,MAAA;EAQ1B;EAcA,SAAA,SAAa,EAAA,MAAA;EAC+B;;;;;;;AA8BxD;AAYA;AAOA;EAgBiB,SAAA,iBAAc,CAAA,EA5KA,iBA4KA;;;;;;;;AA6B/B;AAWA;AAQA;AAeA;AAaA;;;AAEK,UA1OY,mBAAA,CA0OZ;EAAkB,SAAA,WAAA,EAAA,MAAA,GAAA,MAAA;;;;;;;;UAhON,eAAA;qBACI,cAAc;mBAChB,cAAc;wBACT;wBACA;;;;oBAIJ;6BACS,SAAS;yBACb;;;;;;;wBAAmB;sBAQtB;;;;;;;;;gCASU;;;;;;;UAQf,uBAAA;;;;;;;;;;;;UAaA,gBAAA;;;;;;;uBAOM,cAAc;kBACnB;yBACO;8BACK,SAAS;;;;;;;KAQ3B,YAAA;;;;;;;KAcA,aAAA;;qBAC4C;;;;;;;;;;;;;;;kBAWF;;;;;;;;;;;;;;;;;;;iBASiB;;;;;;;yBAEjB;kBAA8B;;;kBACtC;;;;;;;UAO7B,gBAAA;;;;;;;;;;;UAYA,aAAA;iBACA;;;;;KAML,iBAAA;;;;;;;UAgBK,cAAA;;;wBAGO,SAAS;;;;;;;0BAOP,SAAS;;;;;;;;sBAQb,cAAc;;;;;;;;;;UAWnB,qBAAA;;;;;;;;;;KAWL,UAAA;;;;;;;;;UAQK,UAAA;;;wBAGO,SAAS;;;;;;;;;;;KAYrB,kBAAA,UAA4B,aAAa;;;;;;;;;;;;KAazC,yBAAA,iBACG,cAAc,wBACxB"}

package/dist/contracts/session-store.d.ts

@@ -124,8 +124,16 @@ interface SessionStoreExt extends SessionStore {
    * workflow-run attachments, and audit entries (RP-6) - **plus the
    * session's content**: its `session_messages` rows (with their FTS and
    * vector index entries) and any episodes scoped to the session
-   * (store-01). After this call the conversation is no longer retrievable
-   * through `memory.session.*` search surfaces. A no-op for an unknown id.
+   * (store-01). The cascade also erases the checkpoints of suspended
+   * runs (W-005): `workflow_checkpoints` / `workflow_pending_writes`
+   * rows for every thread linked to the session, whether through the
+   * workflow-run attachment mapping or through the `sessionId`
+   * checkpoint metadata the agent runtime stamps on HITL suspends -
+   * those snapshots embed the full conversation. After this call the
+   * conversation is no longer retrievable through `memory.session.*`
+   * search surfaces nor resumable from its checkpoints. A no-op for an
+   * unknown id. Custom implementations must honour the same contract in
+   * full - leaving any of these surfaces behind defeats erasure.
    */
   deleteSession(sessionId: string): Promise<void>;
   /**

package/dist/contracts/session-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-store.d.ts","names":[],"sources":["../../src/contracts/session-store.ts"],"sourcesContent":[],"mappings":";;;;;;;AAUA;AAmBA;AAcA;AAqBA;AAmBA;AAC0B,UA1ET,eAAA,CA0ES;EAAkB,SAAA,EAAA,EAAA,MAAA;EACH,SAAA,MAAA,EAAA,MAAA;EAAR,SAAA,OAAA,EAAA,MAAA;EAEjB,SAAA,KAAA,CAAA,EAAA,MAAA;EAAL,SAAA,SAAA,EAAA,MAAA;EACgB,SAAA,SAAA,CAAA,EAAA,MAAA;EAAd,SAAA,QAAA,CAAA,EAAA,MAAA;EAAR,SAAA,IAAA,CAAA,EAtEa,aAsEb,CAAA,MAAA,CAAA;;;;;;;;;;AAQsC,UAnE1B,kBAAA,CAmE0B;EAAgB,SAAA,EAAA,EAAA,MAAA;EACF,SAAA,WAAA,EAAA,MAAA;EAAd,SAAA,YAAA,EAAA,MAAA;EAAR,SAAA,SAAA,CAAA,EAAA,MAAA;EAEV,SAAA,IAAA,CAAA,EAjEP,aAiEO,CAAA,MAAA,CAAA;;;;;;AAezB;;AAIsC,UA3ErB,kBAAA,CA2EqB;EAAd,SAAA,SAAA,EAAA,MAAA;EAAR,SAAA,UAAA,EAAA,MAAA;EAMJ,SAAA,QAAA,EAAA,MAAA;EACP,SAAA,UAAA,EAAA,MAAA;EAEqB,SAAA,MAAA,EAAA,SAAA,GAAA,WAAA,GAAA,WAAA,GAAA,QAAA;;;;;;;;;;;;;;;UA/DT,iBAAA;;;;;;;;;;sBAUK,SAAS;;;;;;;;UASd,YAAA;0BACS,kBAAkB;iCACX,QAAQ;sBAE9B,KAAK,sCACX,QAAQ,cAAc;0CACe,QAAQ,mBAAmB;qDAChB;uBAE9B,qBAAqB;mDACO;iCAClB,QAAQ;2CAEE,gBAAgB;mCACxB,QAAQ,cAAc;yBAEhC,qBAAqB;uCACP,QAAQ,cAAc;;;;;;;;;;;;;UAc5C,eAAA,SAAwB;;gCAET;;gBAEhB,QAAQ,cAAc;;2FAM1B,+BACP;;0BAEqB,oBAAoB;;;;MAKzC,QAAQ,cAAc;;4CAEiB;;;;;;;;;oCASR;;;;;;;;;;MAU9B"}
+{"version":3,"file":"session-store.d.ts","names":[],"sources":["../../src/contracts/session-store.ts"],"sourcesContent":[],"mappings":";;;;;;;AAUA;AAmBA;AAcA;AAqBA;AAmBA;AAC0B,UA1ET,eAAA,CA0ES;EAAkB,SAAA,EAAA,EAAA,MAAA;EACH,SAAA,MAAA,EAAA,MAAA;EAAR,SAAA,OAAA,EAAA,MAAA;EAEjB,SAAA,KAAA,CAAA,EAAA,MAAA;EAAL,SAAA,SAAA,EAAA,MAAA;EACgB,SAAA,SAAA,CAAA,EAAA,MAAA;EAAd,SAAA,QAAA,CAAA,EAAA,MAAA;EAAR,SAAA,IAAA,CAAA,EAtEa,aAsEb,CAAA,MAAA,CAAA;;;;;;;;;;AAQsC,UAnE1B,kBAAA,CAmE0B;EAAgB,SAAA,EAAA,EAAA,MAAA;EACF,SAAA,WAAA,EAAA,MAAA;EAAd,SAAA,YAAA,EAAA,MAAA;EAAR,SAAA,SAAA,CAAA,EAAA,MAAA;EAEV,SAAA,IAAA,CAAA,EAjEP,aAiEO,CAAA,MAAA,CAAA;;;;;;AAezB;;AAIsC,UA3ErB,kBAAA,CA2EqB;EAAd,SAAA,SAAA,EAAA,MAAA;EAAR,SAAA,UAAA,EAAA,MAAA;EAMJ,SAAA,QAAA,EAAA,MAAA;EACP,SAAA,UAAA,EAAA,MAAA;EAEqB,SAAA,MAAA,EAAA,SAAA,GAAA,WAAA,GAAA,WAAA,GAAA,QAAA;;;;;;;;;;;;;;;UA/DT,iBAAA;;;;;;;;;;sBAUK,SAAS;;;;;;;;UASd,YAAA;0BACS,kBAAkB;iCACX,QAAQ;sBAE9B,KAAK,sCACX,QAAQ,cAAc;0CACe,QAAQ,mBAAmB;qDAChB;uBAE9B,qBAAqB;mDACO;iCAClB,QAAQ;2CAEE,gBAAgB;mCACxB,QAAQ,cAAc;yBAEhC,qBAAqB;uCACP,QAAQ,cAAc;;;;;;;;;;;;;UAc5C,eAAA,SAAwB;;gCAET;;gBAEhB,QAAQ,cAAc;;2FAM1B,+BACP;;0BAEqB,oBAAoB;;;;MAKzC,QAAQ,cAAc;;4CAEiB;;;;;;;;;;;;;;;;;oCAiBR;;;;;;;;;;MAU9B"}

package/dist/contracts/tool.d.ts

@@ -94,6 +94,12 @@ interface Tool<TInput = unknown, TOutput = unknown, TDeps = unknown> {
    * the input-token cost bounded for installations with dozens of
    * MCP-derived tools.
    *
+   * Naming note (W-127): the snake_case is DELIBERATE - this field
+   * mirrors the wire-level `defer_loading` flag of the Anthropic
+   * tool-use surface one-to-one, so grep and serialized payloads
+   * match. It is the only snake_case field on `Tool` by design, not
+   * an oversight.
+   *
    * @default `false`
    */
   readonly defer_loading?: boolean;
@@ -159,6 +165,24 @@ interface Tool<TInput = unknown, TOutput = unknown, TDeps = unknown> {
    */
   execute(input: TInput, ctx: ToolExecutionContext<TDeps>): Promise<TOutput | ToolReturn<TOutput> | undefined>;
 }
+/**
+ * Existentially-typed {@link Tool} for collection seams (W-100).
+ *
+ * `Tool` is invariant in `TInput` (the `needsApproval` /
+ * `idempotencyKey` predicate properties are contravariant in it), so a
+ * concretely-typed `Tool<{ q: string }, number, D>` is NOT assignable
+ * to `Tool<unknown, unknown, D>` - which forced `as unknown as Tool`
+ * casts wherever tools are collected. `AnyTool` erases `TInput` /
+ * `TOutput` existentially, following the `HandoffEntry` precedent in
+ * `@graphorin/agent`.
+ *
+ * Use it on COLLECTION seams (`createAgent({ tools })`, executor
+ * options, registries); implement tools against the typed `Tool` via
+ * the `tool({...})` factory.
+ *
+ * @stable
+ */
+type AnyTool<TDeps = unknown> = Tool<any, any, TDeps>;
 /**
  * Worked example for a `Tool`. Type-parameterized on the same generics
  * as `Tool`, so a `ToolExample` for `Tool<{ q: string }, { hits: T[] }>`
@@ -197,6 +221,15 @@ interface ResolvedTool<TInput = unknown, TOutput = unknown, TDeps = unknown> ext
  * @stable
  */
 interface ToolReturn<TOutput = unknown> {
+  /**
+   * W-115: envelope brand set by the {@link toolReturn} factory.
+   * `Symbol.for`, so duplicate package copies agree. Prefer branding:
+   * the structural fallback in the executor is deliberately narrow
+   * (own keys within `{output, contentParts, taint}`), and plain data
+   * that happens to be exactly `{ output: X }` is ambiguous by
+   * construction - brand it (or rename the field) to disambiguate.
+   */
+  readonly [TOOL_RETURN_BRAND]?: true;
   readonly output: TOutput;
   readonly contentParts?: ReadonlyArray<MessageContent>;
   /**
@@ -213,6 +246,47 @@ interface ToolReturn<TOutput = unknown> {
     readonly sourceKind?: string;
   };
 }
+/**
+ * W-115: cross-realm brand for the {@link ToolReturn} envelope
+ * (`SECRET_VALUE_BRAND` precedent - `Symbol.for` survives duplicate
+ * package copies).
+ *
+ * @stable
+ */
+declare const TOOL_RETURN_BRAND: unique symbol;
+/**
+ * W-115: build a BRANDED {@link ToolReturn} envelope. The executor
+ * unwraps branded envelopes unconditionally; unbranded objects fall to
+ * a deliberately narrow structural sniff (own keys within
+ * `{output, contentParts, taint}`), so a tool legitimately returning
+ * `{ output, exitCode, stderr }` is no longer silently stripped to its
+ * `output` field.
+ *
+ * @stable
+ */
+declare function toolReturn<TOutput>(fields: {
+  readonly output: TOutput;
+  readonly contentParts?: ReadonlyArray<MessageContent>;
+  readonly taint?: ToolReturn<TOutput>['taint'];
+}): ToolReturn<TOutput>;
+/**
+ * W-115: the ONE guard for the ToolReturn envelope (the executor and
+ * the registry example-normalizer both consume it). Brand first; the
+ * structural fallback accepts only objects whose OWN enumerable keys
+ * all belong to the canonical envelope shape - `{output, exitCode}`
+ * style process results pass through intact.
+ *
+ * @stable
+ */
+declare function isToolReturnEnvelope<TOutput = unknown>(value: unknown): value is ToolReturn<TOutput>;
+/**
+ * W-115: `true` when {@link isToolReturnEnvelope} matched WITHOUT the
+ * brand - observability for the future deprecation of the structural
+ * sniff.
+ *
+ * @stable
+ */
+declare function isUnbrandedToolReturn(value: unknown): boolean;
 /**
  * Per-call execution context handed to `Tool.execute(...)`. Carries the
  * stable `toolCallId`, the parent `RunContext`, an `AbortSignal` tied to
@@ -273,5 +347,5 @@ interface ToolSecretsAccessor {
   }): Promise<SecretValue | null>;
 }
 //#endregion
-export { ResolvedTool, Tool, ToolExample, ToolExecutionContext, ToolReturn, ToolSecretsAccessor };
+export { AnyTool, ResolvedTool, TOOL_RETURN_BRAND, Tool, ToolExample, ToolExecutionContext, ToolReturn, ToolSecretsAccessor, isToolReturnEnvelope, isUnbrandedToolReturn, toolReturn };
 //# sourceMappingURL=tool.d.ts.map

package/dist/contracts/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","names":[],"sources":["../../src/contracts/tool.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;AAkCA;;;;;;;;;;;;;AAmD6B,UAnDZ,IAmDY,CAAA,SAAA,OAAA,EAAA,UAAA,OAAA,EAAA,QAAA,OAAA,CAAA,CAAA;EAEI,SAAA,IAAA,EAAA,MAAA;EA6BD,SAAA,WAAA,EAAA,MAAA;EAOgB,SAAA,WAAA,EAtFxB,aAsFwB,CAtFV,MAsFU,CAAA;EAAQ,SAAA,YAAA,CAAA,EArF9B,aAqF8B,CArFhB,OAqFgB,CAAA;EAApB;;;;;EAuB3B,SAAA,aAAA,CAAA,EAAA,OAAA,GAAA,CAAA,CAAA,KAAA,EApGM,MAoGN,EAAA,GAAA,EApGmB,oBAoGnB,CApGwC,KAoGxC,CAAA,EAAA,GAAA,OAAA,GApG6D,OAoG7D,CAAA,OAAA,CAAA,CAAA;EACO;;;;;;;;EAyBO,SAAA,aAAA,CAAA,EArHI,aAqHJ;EAAlB;EAAO,SAAA,IAAA,CAAA,EAnHM,aAmHN,CAAA,MAAA,CAAA;EAUK;;;;;;AAcjB;EACe,SAAA,aAAA,CAAA,EAAA,UAAA,GAAA,YAAA;EAAQ;;;;;EAQO,SAAA,cAAA,CAAA,EAtIF,aAsIE,CAAA,MAAA,CAAA;EAAY;;;AAU1C;;EAEwC,SAAA,WAAA,CAAA,EAlJC,WAkJD;EAAd;;AAyB1B;;;;;EAKmB,SAAA,eAAA,CAAA,EAlKU,eAkKV;EAMC;EAaG,SAAA,mBAAA,CAAA,EAnLU,yBAmLV;EAAY;AAanC;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAnKgC;;;;;;;sBAOV,cAAc,YAAY,QAAQ;;;;;;;;;;;;;;6BAc3B;;;;;;;oCAQlB,aACF,qBAAqB,oBACd;;;;;;;;;;;;;;4BAcY,YAAY;;;;;;;;iBAS7B,aACF,qBAAqB,SACzB,QAAQ,UAAU,WAAW;;;;;;;;;UAUjB;kBACC;mBACC,UAAU,WAAW;;;;;;;;;;;UAYvB,2EACP,KAAK,QAAQ,SAAS;yBACP;qBACJ;;8BAES;;;;8BAIA,YAAY;;;;;;;;;UAUzB;mBACE;0BACO,cAAc;;;;;;;;;;;;;;;;;;;;;;;;UAyBvB;;uBAEM,WAAW;mBACf;mBACA;mBACA;;;;;;oBAMC;;;;;;;;;;;;;uBAaG;;;;;;;;;;;;UAaN,mBAAA;;;;;;;;;MAUZ,QAV+B,WAAA;;;MAc/B,QAJO,WAAA"}
+{"version":3,"file":"tool.d.ts","names":[],"sources":["../../src/contracts/tool.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;AAkCA;;;;;;;;;;;;;AAmD6B,UAnDZ,IAmDY,CAAA,SAAA,OAAA,EAAA,UAAA,OAAA,EAAA,QAAA,OAAA,CAAA,CAAA;EAEI,SAAA,IAAA,EAAA,MAAA;EAmCD,SAAA,WAAA,EAAA,MAAA;EAOgB,SAAA,WAAA,EA5FxB,aA4FwB,CA5FV,MA4FU,CAAA;EAAQ,SAAA,YAAA,CAAA,EA3F9B,aA2F8B,CA3FhB,OA2FgB,CAAA;EAApB;;;;;EAuB3B,SAAA,aAAA,CAAA,EAAA,OAAA,GAAA,CAAA,CAAA,KAAA,EA1GM,MA0GN,EAAA,GAAA,EA1GmB,oBA0GnB,CA1GwC,KA0GxC,CAAA,EAAA,GAAA,OAAA,GA1G6D,OA0G7D,CAAA,OAAA,CAAA,CAAA;EACO;;;;;;;;EAyBO,SAAA,aAAA,CAAA,EA3HI,aA2HJ;EAAlB;EAAO,SAAA,IAAA,CAAA,EAzHM,aAyHN,CAAA,MAAA,CAAA;EAqBA;AASZ;;;;;;EAciB,SAAA,aAAY,CAAA,EAAA,UAAA,GAAA,YAAA;EACd;;;;;EAIe,SAAA,cAAA,CAAA,EA5JF,aA4JE,CAAA,MAAA,CAAA;EAIA;;;;AAU9B;EASY,SAAA,WAAA,CAAA,EAnL6B,WAmL7B;EACO;;;;AAwBnB;AAYA;;EAEwC,SAAA,eAAA,CAAA,EA5MX,eA4MW;EAAd;EACI,SAAA,mBAAA,CAAA,EA3MG,yBA2MH;EAAX;;;;AAmBnB;AAmBA;AAgBA;EAEkC,SAAA,UAAA,CAAA,EAAA,OAAA;EAAX;;;;;;;AAmCvB;;;;;;;;;;;;;;;;;;;gCAnQgC;;;;;;;sBAOV,cAAc,YAAY,QAAQ;;;;;;;;;;;;;;6BAc3B;;;;;;;oCAQlB,aACF,qBAAqB,oBACd;;;;;;;;;;;;;;4BAcY,YAAY;;;;;;;;iBAS7B,aACF,qBAAqB,SACzB,QAAQ,UAAU,WAAW;;;;;;;;;;;;;;;;;;;KAqBtB,2BAA2B,eAAe;;;;;;;;UASrC;kBACC;mBACC,UAAU,WAAW;;;;;;;;;;;UAYvB,2EACP,KAAK,QAAQ,SAAS;yBACP;qBACJ;;8BAES;;;;8BAIA,YAAY;;;;;;;;;UAUzB;;;;;;;;;YASL,iBAAA;mBACO;0BACO,cAAc;;;;;;;;;;;;;;;;;;;;;;cAuB3B;;;;;;;;;;;iBAYG;mBACG;0BACO,cAAc;mBACrB,WAAW;IAC1B,WAAW;;;;;;;;;;iBAkBC,kEAEJ,WAAW;;;;;;;;iBAiBP,qBAAA;;;;;;;;;;UAgBC;;uBAEM,WAAW;mBACf;mBACA;mBACA;;;;;;oBAMC;;;;;;;;;;;;;uBAaG;;;;;;;;;;;;UAaN,mBAAA;;;;;;;;;MAUZ,QAV+B,WAAA;;;MAc/B,QAJO,WAAA"}

package/dist/contracts/tool.js

@@ -0,0 +1,57 @@
+//#region src/contracts/tool.ts
+/**
+* W-115: cross-realm brand for the {@link ToolReturn} envelope
+* (`SECRET_VALUE_BRAND` precedent - `Symbol.for` survives duplicate
+* package copies).
+*
+* @stable
+*/
+const TOOL_RETURN_BRAND = Symbol.for("graphorin.ToolReturn");
+/**
+* W-115: build a BRANDED {@link ToolReturn} envelope. The executor
+* unwraps branded envelopes unconditionally; unbranded objects fall to
+* a deliberately narrow structural sniff (own keys within
+* `{output, contentParts, taint}`), so a tool legitimately returning
+* `{ output, exitCode, stderr }` is no longer silently stripped to its
+* `output` field.
+*
+* @stable
+*/
+function toolReturn(fields) {
+	return {
+		[TOOL_RETURN_BRAND]: true,
+		output: fields.output,
+		...fields.contentParts !== void 0 ? { contentParts: fields.contentParts } : {},
+		...fields.taint !== void 0 ? { taint: fields.taint } : {}
+	};
+}
+/**
+* W-115: the ONE guard for the ToolReturn envelope (the executor and
+* the registry example-normalizer both consume it). Brand first; the
+* structural fallback accepts only objects whose OWN enumerable keys
+* all belong to the canonical envelope shape - `{output, exitCode}`
+* style process results pass through intact.
+*
+* @stable
+*/
+function isToolReturnEnvelope(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	if (value[TOOL_RETURN_BRAND] === true) return true;
+	if (!Object.hasOwn(value, "output")) return false;
+	for (const key of Object.keys(value)) if (key !== "output" && key !== "contentParts" && key !== "taint") return false;
+	return true;
+}
+/**
+* W-115: `true` when {@link isToolReturnEnvelope} matched WITHOUT the
+* brand - observability for the future deprecation of the structural
+* sniff.
+*
+* @stable
+*/
+function isUnbrandedToolReturn(value) {
+	return isToolReturnEnvelope(value) && value[TOOL_RETURN_BRAND] !== true;
+}
+
+//#endregion
+export { TOOL_RETURN_BRAND, isToolReturnEnvelope, isUnbrandedToolReturn, toolReturn };
+//# sourceMappingURL=tool.js.map

package/dist/contracts/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","names":["TOOL_RETURN_BRAND: unique symbol"],"sources":["../../src/contracts/tool.ts"],"sourcesContent":["import type { MessageContent } from '../types/message.js';\nimport type { RunContext } from '../types/run.js';\nimport type {\n  ContentChunk,\n  InboundSanitizationPolicy,\n  MemoryGuardTier,\n  SandboxPolicy,\n  SideEffectClass,\n  ToolSource,\n  ToolTrustClass,\n  TruncationStrategy,\n} from '../types/tool.js';\nimport type { ZodLikeSchema } from '../utils/validation.js';\nimport type { Logger } from './logger.js';\nimport type { ModelHint, ModelSpec } from './preferred-model.js';\nimport type { Tracer } from './tracer.js';\n\n/**\n * Pluggable function call exposed to an LLM. Concrete `Tool` instances\n * are produced by the `tool({...})` factory in `@graphorin/tools` and\n * by the MCP / Skills loaders. The interface lives in core because every\n * package above the persistence layer (agent runtime, workflow engine,\n * server, sessions, observability, …) carries `Tool[]` references on\n * its public surface.\n *\n * The interface is intentionally minimal - extension fields covered by\n * later phases (per-tool `secretsAllowed` ACL, inbound sanitization\n * policy, result truncation strategy, streaming hint, …) are added\n * **additively** by their owning packages so that v0.1 consumers can\n * type their tool list against `Tool<...>` today without having to\n * worry about future fields.\n *\n * @stable\n */\nexport interface Tool<TInput = unknown, TOutput = unknown, TDeps = unknown> {\n  readonly name: string;\n  readonly description: string;\n  readonly inputSchema: ZodLikeSchema<TInput>;\n  readonly outputSchema?: ZodLikeSchema<TOutput>;\n  /**\n   * Either a static boolean or a predicate consulted at runtime against\n   * the realized input. `true` means the runtime suspends the run with a\n   * `tool.approval.requested` event before the tool executes.\n   */\n  readonly needsApproval?:\n    | boolean\n    | ((input: TInput, ctx: ToolExecutionContext<TDeps>) => boolean | Promise<boolean>);\n  /**\n   * Sandbox isolation level. Defaults are picked by\n   * `@graphorin/security`. ADVISORY in the default agent build (AG-18):\n   * inline `config.tools` closures cannot be serialised out-of-process,\n   * so the resolved policy is surfaced on the `tool.execute` span /\n   * audit but the tool runs in-process. Real isolation applies to\n   * module-loadable (skill / MCP) tools.\n   */\n  readonly sandboxPolicy?: SandboxPolicy;\n  /** Free-form labels surfaced to operators and to the model. */\n  readonly tags?: ReadonlyArray<string>;\n  /**\n   * Sequential execution mode hints. Tools tagged `'sequential'` are\n   * never executed in parallel with each other; the executor serializes\n   * them inside the per-step batch.\n   *\n   * @default `'parallel'`\n   */\n  readonly executionMode?: 'parallel' | 'sequential';\n  /**\n   * Per-tool secrets ACL. Tool execution is wrapped in a scope where\n   * `ctx.secrets.require(...)` only resolves keys present here.\n   * Empty / undefined means the tool may not request any secret.\n   */\n  readonly secretsAllowed?: ReadonlyArray<string>;\n  /**\n   * Sensitivity ceiling of the tool's input + output payload. Used by\n   * the redaction validator to decide whether the result may flow to a\n   * given sink (provider / exporter).\n   */\n  readonly sensitivity?: import('../types/sensitivity.js').Sensitivity;\n  /**\n   * Memory-modification guard tier (DEC-153). ACTIVE when the agent is\n   * created with `memory` wired (SDF-1): the runtime binds a scope-aware\n   * region reader over working memory and the executor snapshots/verifies\n   * the region around guarded calls. Without `memory` the guard is\n   * skipped and the agent emits a one-time WARN.\n   */\n  readonly memoryGuardTier?: MemoryGuardTier;\n  /** Inbound prompt-injection sanitization policy. */\n  readonly inboundSanitization?: InboundSanitizationPolicy;\n  /**\n   * When `true`, an inbound-sanitization hit returns `ToolError({ kind:\n   * 'inbound_sanitization_blocked' })` instead of forwarding the\n   * (sanitized) result. Intended for regulated deployments.\n   *\n   * @default `false`\n   */\n  readonly failClosed?: boolean;\n  /**\n   * Defer the tool from the per-step catalogue until the model invokes\n   * the built-in `tool_search` to look it up. Tools with deferred\n   * loading are not advertised to the model on every step, which keeps\n   * the input-token cost bounded for installations with dozens of\n   * MCP-derived tools.\n   *\n   * Naming note (W-127): the snake_case is DELIBERATE - this field\n   * mirrors the wire-level `defer_loading` flag of the Anthropic\n   * tool-use surface one-to-one, so grep and serialized payloads\n   * match. It is the only snake_case field on `Tool` by design, not\n   * an oversight.\n   *\n   * @default `false`\n   */\n  readonly defer_loading?: boolean;\n  /**\n   * Maximum number of tokens the assembled tool result may carry into\n   * the conversation history. `0` disables the cap (logs a one-time\n   * WARN at registration). Counted against text-shaped output and\n   * text-shaped `contentParts` entries; non-text parts pass through.\n   *\n   * @default `16384`\n   */\n  readonly maxResultTokens?: number;\n  /** Truncation strategy applied when `maxResultTokens` is exceeded. */\n  readonly truncationStrategy?: TruncationStrategy;\n  /**\n   * Worked examples shown to the model alongside the tool's\n   * description. Bounded `[1, 5]` - overflow emits a one-time WARN at\n   * registration. Each example's `input` and `output` is validated\n   * against the tool's `inputSchema` / `outputSchema`.\n   */\n  readonly examples?: ReadonlyArray<ToolExample<TInput, TOutput>>;\n  /**\n   * Render examples eagerly (every step) regardless of\n   * `defer_loading`. When undefined the runtime applies the auto-rule:\n   * `defer_loading: true` ⇒ `false`; `defer_loading: false` ⇒ `true`;\n   * neither ⇒ `undefined` (the agent runtime decides at assembly time).\n   */\n  readonly examplesEagerlyRendered?: boolean;\n  /**\n   * REQUIRED side-effect classification. v0.1 transition mode emits a\n   * one-time WARN per tool name on missing classification and applies\n   * the conservative deferred default `'side-effecting'`; v0.2 may\n   * promote the WARN to a registration error.\n   */\n  readonly sideEffectClass?: SideEffectClass;\n  /**\n   * Optional callback returning a deterministic dedup key per\n   * `(input, ctx)` tuple. REQUIRED-by-WARN for `'side-effecting'` /\n   * `'external-stateful'` tools. The framework does not validate\n   * determinism - that is the operator's contract.\n   */\n  readonly idempotencyKey?: (\n    input: TInput,\n    ctx: ToolExecutionContext<TDeps>,\n  ) => string | Promise<string>;\n  /**\n   * Opt-in flag for streaming-tool execution. The `?: true` typing\n   * rejects `streamingHint: false` on purpose - absence is the\n   * canonical \"non-streaming\" signal preserving v0.1 behaviour. When\n   * `true`, `Tool.execute(...)` may call `ctx.streamContent(...)` /\n   * `ctx.reportProgress(...)` and may return `Promise<void>`.\n   */\n  readonly streamingHint?: true;\n  /**\n   * Per-tool author-time model hint. Either a cost-tier vocabulary\n   * literal (`'fast' | 'balanced' | 'smart'`) OR an explicit\n   * `ModelSpec` that always wins over the agent-side tier mapping.\n   */\n  readonly preferredModel?: ModelHint | ModelSpec;\n  /**\n   * Execute the tool. Concrete implementations may return either a raw\n   * `TOutput` or a `ToolReturn<TOutput>` envelope when extra content\n   * parts (images, files, …) need to be appended to the conversation.\n   * Streaming-hint tools may also return `void` once the per-chunk\n   * buffer has been populated.\n   */\n  execute(\n    input: TInput,\n    ctx: ToolExecutionContext<TDeps>,\n  ): Promise<TOutput | ToolReturn<TOutput> | undefined>;\n}\n\n/**\n * Existentially-typed {@link Tool} for collection seams (W-100).\n *\n * `Tool` is invariant in `TInput` (the `needsApproval` /\n * `idempotencyKey` predicate properties are contravariant in it), so a\n * concretely-typed `Tool<{ q: string }, number, D>` is NOT assignable\n * to `Tool<unknown, unknown, D>` - which forced `as unknown as Tool`\n * casts wherever tools are collected. `AnyTool` erases `TInput` /\n * `TOutput` existentially, following the `HandoffEntry` precedent in\n * `@graphorin/agent`.\n *\n * Use it on COLLECTION seams (`createAgent({ tools })`, executor\n * options, registries); implement tools against the typed `Tool` via\n * the `tool({...})` factory.\n *\n * @stable\n */\n// biome-ignore lint/suspicious/noExplicitAny: existential TInput/TOutput (see above)\nexport type AnyTool<TDeps = unknown> = Tool<any, any, TDeps>;\n\n/**\n * Worked example for a `Tool`. Type-parameterized on the same generics\n * as `Tool`, so a `ToolExample` for `Tool<{ q: string }, { hits: T[] }>`\n * cannot specify an `input` shape that does not match.\n *\n * @stable\n */\nexport interface ToolExample<TInput = unknown, TOutput = unknown> {\n  readonly input: TInput;\n  readonly output: TOutput | ToolReturn<TOutput>;\n  readonly comment?: string;\n}\n\n/**\n * Resolved record returned by the `ToolRegistry` getter. Carries every\n * non-public registration-time field downstream layers consume\n * (sanitization, audit, retrieval, side-effect classification,\n * collision resolution, …) so consumers do not have to recompute it.\n *\n * @stable\n */\nexport interface ResolvedTool<TInput = unknown, TOutput = unknown, TDeps = unknown>\n  extends Tool<TInput, TOutput, TDeps> {\n  readonly __trustClass: ToolTrustClass;\n  readonly __source: ToolSource;\n  readonly __effectiveDeferLoading: boolean;\n  readonly __sideEffectClass: SideEffectClass;\n  readonly __hasIdempotencyKey: boolean;\n  readonly __streamingHint: boolean;\n  readonly __exampleCount: number;\n  readonly __preferredModel?: ModelHint | ModelSpec;\n}\n\n/**\n * Optional return envelope: pairs a typed `output` (passed to the model)\n * with extra `contentParts` that are appended verbatim to the\n * conversation (images, files, audio, …).\n *\n * @stable\n */\nexport interface ToolReturn<TOutput = unknown> {\n  /**\n   * W-115: envelope brand set by the {@link toolReturn} factory.\n   * `Symbol.for`, so duplicate package copies agree. Prefer branding:\n   * the structural fallback in the executor is deliberately narrow\n   * (own keys within `{output, contentParts, taint}`), and plain data\n   * that happens to be exactly `{ output: X }` is ambiguous by\n   * construction - brand it (or rename the field) to disambiguate.\n   */\n  readonly [TOOL_RETURN_BRAND]?: true;\n  readonly output: TOutput;\n  readonly contentParts?: ReadonlyArray<MessageContent>;\n  /**\n   * C6: per-result taint override the data-flow ledger honours when\n   * recording this output. Lets a FIRST-PARTY tool whose CONTENT is not\n   * first-party (e.g. memory recall returning quarantined /\n   * foreign-provenance facts) re-arm the taint ledger, closing the\n   * cross-session poisoning leg. Flags only ever WIDEN the derived label\n   * (they cannot launder an untrusted tool's output into trusted).\n   */\n  readonly taint?: {\n    readonly untrusted?: boolean;\n    readonly sensitive?: boolean;\n    readonly sourceKind?: string;\n  };\n}\n\n/**\n * W-115: cross-realm brand for the {@link ToolReturn} envelope\n * (`SECRET_VALUE_BRAND` precedent - `Symbol.for` survives duplicate\n * package copies).\n *\n * @stable\n */\nexport const TOOL_RETURN_BRAND: unique symbol = Symbol.for('graphorin.ToolReturn');\n\n/**\n * W-115: build a BRANDED {@link ToolReturn} envelope. The executor\n * unwraps branded envelopes unconditionally; unbranded objects fall to\n * a deliberately narrow structural sniff (own keys within\n * `{output, contentParts, taint}`), so a tool legitimately returning\n * `{ output, exitCode, stderr }` is no longer silently stripped to its\n * `output` field.\n *\n * @stable\n */\nexport function toolReturn<TOutput>(fields: {\n  readonly output: TOutput;\n  readonly contentParts?: ReadonlyArray<MessageContent>;\n  readonly taint?: ToolReturn<TOutput>['taint'];\n}): ToolReturn<TOutput> {\n  return {\n    [TOOL_RETURN_BRAND]: true,\n    output: fields.output,\n    ...(fields.contentParts !== undefined ? { contentParts: fields.contentParts } : {}),\n    ...(fields.taint !== undefined ? { taint: fields.taint } : {}),\n  };\n}\n\n/**\n * W-115: the ONE guard for the ToolReturn envelope (the executor and\n * the registry example-normalizer both consume it). Brand first; the\n * structural fallback accepts only objects whose OWN enumerable keys\n * all belong to the canonical envelope shape - `{output, exitCode}`\n * style process results pass through intact.\n *\n * @stable\n */\nexport function isToolReturnEnvelope<TOutput = unknown>(\n  value: unknown,\n): value is ToolReturn<TOutput> {\n  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;\n  if ((value as Record<PropertyKey, unknown>)[TOOL_RETURN_BRAND] === true) return true;\n  if (!Object.hasOwn(value, 'output')) return false;\n  for (const key of Object.keys(value)) {\n    if (key !== 'output' && key !== 'contentParts' && key !== 'taint') return false;\n  }\n  return true;\n}\n\n/**\n * W-115: `true` when {@link isToolReturnEnvelope} matched WITHOUT the\n * brand - observability for the future deprecation of the structural\n * sniff.\n *\n * @stable\n */\nexport function isUnbrandedToolReturn(value: unknown): boolean {\n  return (\n    isToolReturnEnvelope(value) &&\n    (value as unknown as Record<PropertyKey, unknown>)[TOOL_RETURN_BRAND] !== true\n  );\n}\n\n/**\n * Per-call execution context handed to `Tool.execute(...)`. Carries the\n * stable `toolCallId`, the parent `RunContext`, an `AbortSignal` tied to\n * the surrounding agent run, structured tracer / logger handles, the\n * streaming progress / content emitters, and a per-call secrets accessor\n * scoped to the tool's `secretsAllowed` ACL.\n *\n * @stable\n */\nexport interface ToolExecutionContext<TDeps = unknown> {\n  readonly toolCallId: string;\n  readonly runContext: RunContext<TDeps>;\n  readonly signal: AbortSignal;\n  readonly tracer: Tracer;\n  readonly logger: Logger;\n  /**\n   * Per-call secrets accessor. The accessor enforces the tool's\n   * `secretsAllowed` ACL - calling `require(...)` for a key that is\n   * not on the allowlist throws `SecretAccessDeniedError`.\n   */\n  readonly secrets: ToolSecretsAccessor;\n  /**\n   * Emit a progress event to subscribers of `agent.stream(...)`. No-op\n   * on tools without `streamingHint: true` AND on aborted streams. The\n   * counter pair `(current, total?)` is consumer-rendered as a\n   * percentage when both fields are present.\n   */\n  reportProgress(current: number, total?: number, message?: string): void;\n  /**\n   * Emit one chunk of content. Concatenated into the tool's assembled\n   * `output` per the buffer-becomes-output discipline. No-op on tools\n   * without `streamingHint: true` AND on aborted streams.\n   */\n  streamContent(chunk: ContentChunk): void;\n}\n\n/**\n * Per-call secrets accessor surface. Implemented by the executor; the\n * tool author calls `require(...)` to obtain a `SecretValue` wrapper.\n *\n * The accessor is intentionally narrow - the ACL enforcement happens\n * inside `require(...)`, so the tool author never accidentally\n * unwraps a secret outside the tool's permitted set.\n *\n * @stable\n */\nexport interface ToolSecretsAccessor {\n  /**\n   * Resolve a secret by key. Throws `SecretAccessDeniedError` if the\n   * key is not in the tool's `secretsAllowed` allowlist; throws\n   * `SecretRequiredError` (or returns `null` when `optional: true`)\n   * if the key resolves to no value.\n   */\n  require(\n    key: string,\n    options?: { readonly optional?: false },\n  ): Promise<import('./secret-value.js').SecretValue>;\n  require(\n    key: string,\n    options: { readonly optional: true },\n  ): Promise<import('./secret-value.js').SecretValue | null>;\n}\n"],"mappings":";;;;;;;;AAmRA,MAAaA,oBAAmC,OAAO,IAAI,uBAAuB;;;;;;;;;;;AAYlF,SAAgB,WAAoB,QAIZ;AACtB,QAAO;GACJ,oBAAoB;EACrB,QAAQ,OAAO;EACf,GAAI,OAAO,iBAAiB,SAAY,EAAE,cAAc,OAAO,cAAc,GAAG,EAAE;EAClF,GAAI,OAAO,UAAU,SAAY,EAAE,OAAO,OAAO,OAAO,GAAG,EAAE;EAC9D;;;;;;;;;;;AAYH,SAAgB,qBACd,OAC8B;AAC9B,KAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,CAAE,QAAO;AAChF,KAAK,MAAuC,uBAAuB,KAAM,QAAO;AAChF,KAAI,CAAC,OAAO,OAAO,OAAO,SAAS,CAAE,QAAO;AAC5C,MAAK,MAAM,OAAO,OAAO,KAAK,MAAM,CAClC,KAAI,QAAQ,YAAY,QAAQ,kBAAkB,QAAQ,QAAS,QAAO;AAE5E,QAAO;;;;;;;;;AAUT,SAAgB,sBAAsB,OAAyB;AAC7D,QACE,qBAAqB,MAAM,IAC1B,MAAkD,uBAAuB"}

package/dist/contracts/tracer.d.ts

@@ -1,13 +1,42 @@
+import { Sensitivity } from "../types/sensitivity.js";
+
 //#region src/contracts/tracer.d.ts
+
 /**
- * Discriminator union for typed observability spans.
+ * Framework-known discriminators for typed observability spans.
  *
  * The list mirrors the span taxonomy documented for the observability
  * layer; concrete implementations live in `@graphorin/observability`.
+ * Promoting a frequently-used custom span kind (see
+ * {@link CustomSpanType}) into this union is an additive minor change.
  *
  * @stable
  */
-type SpanType = 'agent.run' | 'agent.step' | 'agent.handoff' | 'agent.suspend' | 'agent.resume' | 'provider.generate' | 'provider.stream' | 'tool.execute' | 'tool.approval' | 'memory.read.working' | 'memory.read.session' | 'memory.read.episodic' | 'memory.read.semantic' | 'memory.read.procedural' | 'memory.read.shared' | 'memory.write.working' | 'memory.write.session' | 'memory.write.episodic' | 'memory.write.semantic' | 'memory.write.procedural' | 'memory.write.shared' | 'memory.search.working' | 'memory.search.session' | 'memory.search.episodic' | 'memory.search.semantic' | 'memory.search.procedural' | 'memory.search.shared' | 'memory.consolidate.light' | 'memory.consolidate.standard' | 'memory.consolidate.deep' | 'memory.consolidate.reflect' | 'memory.consolidate.learned-context' | 'memory.search.insight' | 'memory.read.insight' | 'memory.write.insight' | 'memory.conflict' | 'memory.embed' | 'workflow.run' | 'workflow.step' | 'workflow.task' | 'workflow.checkpoint' | 'skill.activate' | 'skill.load' | 'mcp.connect' | 'mcp.call' | 'mcp.list-tools';
+type KnownSpanType = 'agent.run' | 'agent.step' | 'agent.handoff' | 'agent.suspend' | 'agent.resume' | 'provider.generate' | 'provider.stream' | 'tool.execute' | 'tool.approval' | 'memory.read.working' | 'memory.read.session' | 'memory.read.episodic' | 'memory.read.semantic' | 'memory.read.procedural' | 'memory.read.shared' | 'memory.write.working' | 'memory.write.session' | 'memory.write.episodic' | 'memory.write.semantic' | 'memory.write.procedural' | 'memory.write.shared' | 'memory.search.working' | 'memory.search.session' | 'memory.search.episodic' | 'memory.search.semantic' | 'memory.search.procedural' | 'memory.search.shared' | 'memory.consolidate.light' | 'memory.consolidate.standard' | 'memory.consolidate.deep' | 'memory.consolidate.reflect' | 'memory.consolidate.learned-context' | 'memory.search.insight' | 'memory.read.insight' | 'memory.write.insight' | 'memory.conflict' | 'memory.embed' | 'workflow.run' | 'workflow.step' | 'workflow.task' | 'workflow.checkpoint' | 'skill.activate' | 'skill.load' | 'mcp.connect' | 'mcp.call' | 'mcp.list-tools';
+/**
+ * Namespaced escape hatch for user-defined span kinds (W-126): any
+ * string under the `x.` prefix, e.g. `'x.acme.rerank'`. The prefix
+ * keeps typo-safety for the known literals - `'memory.serch.semantic'`
+ * is still a compile error because it does not start with `x.` -
+ * which is why this is a template-literal type and not `string & {}`.
+ *
+ * Convention: `x.<vendor>.<operation>`. Backends and analytics must
+ * tolerate unknown span-type strings (the same policy events already
+ * follow). When a custom kind becomes common, promote it into
+ * {@link KnownSpanType} (additive minor).
+ *
+ * @stable
+ */
+type CustomSpanType = `x.${string}`;
+/**
+ * Discriminator union for typed observability spans: every
+ * {@link KnownSpanType} literal plus the {@link CustomSpanType}
+ * namespaced escape. Exhaustive switches over `SpanType` need a
+ * default branch for the custom domain.
+ *
+ * @stable
+ */
+type SpanType = KnownSpanType | CustomSpanType;
 /**
  * Status of a finished span. Mirrors the OTel status convention with
  * `'ok' | 'error'` short forms instead of the verbose tristate.
@@ -23,6 +52,19 @@ type SpanStatus = 'ok' | 'error' | 'cancelled';
 type SpanAttributes = Readonly<Record<string, SpanAttributeValue>>;
 /** @stable */
 type SpanAttributeValue = string | number | boolean | null | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<boolean>;
+/**
+ * W-094: sensitivity opts for {@link AISpan.addEvent}. Event attributes
+ * used to be un-taggable, so a default-`'public'` export floor dropped
+ * ALL of them - including `exception.type` from `recordException`.
+ *
+ * @stable
+ */
+interface AddEventOptions {
+  /** Default tier applied to every attribute of this event. */
+  readonly sensitivity?: Sensitivity;
+  /** Per-attribute overrides; win over {@link AddEventOptions.sensitivity}. */
+  readonly sensitivityByAttribute?: Readonly<Record<string, Sensitivity>>;
+}
 /**
  * Typed span. Generic over `SpanType` so consumers can specialize a
  * function on a particular span kind without losing the discriminator.
@@ -36,8 +78,14 @@ interface AISpan<T extends SpanType = SpanType> {
   readonly parentId?: string;
   /** Add or replace attributes. Repeated calls are merged (last write wins). */
   setAttributes(attrs: SpanAttributes): void;
-  /** Append a span event (attribute-bearing time-stamped marker). */
-  addEvent(name: string, attrs?: SpanAttributes): void;
+  /**
+   * Append a span event (attribute-bearing time-stamped marker). The
+   * optional `opts` (W-094) tags the event's attributes with a
+   * sensitivity tier so the validation exporter can pass safe ones
+   * through the default-deny floor - untagged attributes keep being
+   * dropped below the floor.
+   */
+  addEvent(name: string, attrs?: SpanAttributes, opts?: AddEventOptions): void;
   /** Record an exception. Multiple calls are kept in the span event log. */
   recordException(err: unknown): void;
   /** Set the terminal status. */
@@ -80,5 +128,5 @@ interface Tracer {
  */
 declare const NOOP_TRACER: Tracer;
 //#endregion
-export { AISpan, NOOP_TRACER, SpanAttributeValue, SpanAttributes, SpanStatus, SpanType, StartSpanOptions, Tracer };
+export { AISpan, AddEventOptions, CustomSpanType, KnownSpanType, NOOP_TRACER, SpanAttributeValue, SpanAttributes, SpanStatus, SpanType, StartSpanOptions, Tracer };
 //# sourceMappingURL=tracer.d.ts.map

package/dist/contracts/tracer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.d.ts","names":[],"sources":["../../src/contracts/tracer.ts"],"sourcesContent":[],"mappings":";;AAQA;AAsDA;AAOA;;;;;AAGY,KAhEA,QAAA,GAgEA,WAAkB,GAAA,YAAA,GAAA,eAAA,GAAA,eAAA,GAAA,cAAA,GAAA,mBAAA,GAAA,iBAAA,GAAA,cAAA,GAAA,eAAA,GAAA,qBAAA,GAAA,qBAAA,GAAA,sBAAA,GAAA,sBAAA,GAAA,wBAAA,GAAA,oBAAA,GAAA,sBAAA,GAAA,sBAAA,GAAA,uBAAA,GAAA,uBAAA,GAAA,yBAAA,GAAA,qBAAA,GAAA,uBAAA,GAAA,uBAAA,GAAA,wBAAA,GAAA,wBAAA,GAAA,0BAAA,GAAA,sBAAA,GAAA,0BAAA,GAAA,6BAAA,GAAA,yBAAA,GAAA,4BAAA,GAAA,oCAAA,GAAA,uBAAA,GAAA,qBAAA,GAAA,sBAAA,GAAA,iBAAA,GAAA,cAAA,GAAA,cAAA,GAAA,eAAA,GAAA,eAAA,GAAA,qBAAA,GAAA,gBAAA,GAAA,YAAA,GAAA,aAAA,GAAA,UAAA,GAAA,gBAAA;;;;;AAe9B;;AAA6C,KAzBjC,UAAA,GAyBiC,IAAA,GAAA,OAAA,GAAA,WAAA;;;;;;AAsB5B,KAxCL,cAAA,GAAiB,QAwCI,CAxCK,MAwCL,CAAA,MAAA,EAxCoB,kBAwCpB,CAAA,CAAA;;AAAsB,KArC3C,kBAAA,GAqC2C,MAAA,GAAA,MAAA,GAAA,OAAA,GAAA,IAAA,GAhCnD,aAgCmD,CAAA,MAAA,CAAA,GA/BnD,aA+BmD,CAAA,MAAA,CAAA,GA9BnD,aA8BmD,CAAA,OAAA,CAAA;;;;;AAavD;;AACuD,UApCtC,MAoCsC,CAAA,UApCrB,QAoCqB,GApCV,QAoCU,CAAA,CAAA;EAAjB,SAAA,IAAA,EAnCrB,CAmCqB;EAA6B,SAAA,EAAA,EAAA,MAAA;EAAP,SAAA,OAAA,EAAA,MAAA;EAK3C,SAAA,QAAA,CAAA,EAAA,MAAA;EACU;EAAjB,aAAA,CAAA,KAAA,EApCa,cAoCb,CAAA,EAAA,IAAA;EACY;EAAP,QAAA,CAAA,IAAA,EAAA,MAAA,EAAA,KAAA,CAAA,EAnCkB,cAmClB,CAAA,EAAA,IAAA;EAAc;EAAY,eAAA,CAAA,GAAA,EAAA,OAAA,CAAA,EAAA,IAAA;EAAR;EACpB,SAAA,CAAA,MAAA,EAhCO,UAgCP,EAAA,OAAA,CAAA,EAAA,MAAA,CAAA,EAAA,IAAA;EAAR;EAES,GAAA,EAAA,EAAA,IAAA;;AASd;;;;;UAjCiB,2BAA2B,WAAW;iBACtC;mBACE;oBACC;;;;;;;;;UAUH,MAAA;sBACK,gBAAgB,iBAAiB,KAAK,OAAO;;;;;iBAKlD,mBACP,iBAAiB,eACZ,OAAO,OAAO,IAAI,QAAQ,KACpC,QAAQ;;cAEC;;;;;;;;cASD,aAAa"}
+{"version":3,"file":"tracer.d.ts","names":[],"sources":["../../src/contracts/tracer.ts"],"sourcesContent":[],"mappings":";;;;;;;AAUA;AA8DA;AAUA;AAQA;AAOA;;;AAA6B,KAvFjB,aAAA,GAuFiB,WAAA,GAAA,YAAA,GAAA,eAAA,GAAA,eAAA,GAAA,cAAA,GAAA,mBAAA,GAAA,iBAAA,GAAA,cAAA,GAAA,eAAA,GAAA,qBAAA,GAAA,qBAAA,GAAA,sBAAA,GAAA,sBAAA,GAAA,wBAAA,GAAA,oBAAA,GAAA,sBAAA,GAAA,sBAAA,GAAA,uBAAA,GAAA,uBAAA,GAAA,yBAAA,GAAA,qBAAA,GAAA,uBAAA,GAAA,uBAAA,GAAA,wBAAA,GAAA,wBAAA,GAAA,0BAAA,GAAA,sBAAA,GAAA,0BAAA,GAAA,6BAAA,GAAA,yBAAA,GAAA,4BAAA,GAAA,oCAAA,GAAA,uBAAA,GAAA,qBAAA,GAAA,sBAAA,GAAA,iBAAA,GAAA,cAAA,GAAA,cAAA,GAAA,eAAA,GAAA,eAAA,GAAA,qBAAA,GAAA,gBAAA,GAAA,YAAA,GAAA,aAAA,GAAA,UAAA,GAAA,gBAAA;;AAG7B;;;;;AAgBA;;;;;;AAeA;;AAA6C,KA3DjC,cAAA,GA2DiC,KAAA,MAAA,EAAA;;;;;;;AA4B7C;;AAAuD,KA7E3C,QAAA,GAAW,aA6EgC,GA7EhB,cA6EgB;;;;;AAavD;;AACuD,KAnF3C,UAAA,GAmF2C,IAAA,GAAA,OAAA,GAAA,WAAA;;;;;;AAM7C,KAlFE,cAAA,GAAiB,QAkFnB,CAlF4B,MAkF5B,CAAA,MAAA,EAlF2C,kBAkF3C,CAAA,CAAA;;AACK,KAhFH,kBAAA,GAgFG,MAAA,GAAA,MAAA,GAAA,OAAA,GAAA,IAAA,GA3EX,aA2EW,CAAA,MAAA,CAAA,GA1EX,aA0EW,CAAA,MAAA,CAAA,GAzEX,aAyEW,CAAA,OAAA,CAAA;;;;;;;;AAYF,UA5EI,eAAA,CA4ES;;yBA5EM;;oCAII,SAChC,eAHkE,WAAA;;;;;;;;UAarD,iBAAiB,WAAW;iBAC5B;;;;;uBAKM;;;;;;;;iCAQU,uBAAuB;;;;oBAIpC;;;;;;;;;UAUH,2BAA2B,WAAW;iBACtC;mBACE;oBACC;;;;;;;;;UAUH,MAAA;sBACK,gBAAgB,iBAAiB,KAAK,OAAO;;;;;iBAKlD,mBACP,iBAAiB,eACZ,OAAO,OAAO,IAAI,QAAQ,KACpC,QAAQ;;cAEC;;;;;;;;cASD,aAAa"}

package/dist/contracts/tracer.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracer.js","names":["NOOP_TRACER: Tracer"],"sources":["../../src/contracts/tracer.ts"],"sourcesContent":["/**\n * Discriminator union for typed observability spans.\n *\n * The list mirrors the span taxonomy documented for the observability\n * layer; concrete implementations live in `@graphorin/observability`.\n *\n * @stable\n */\nexport type SpanType =\n  | 'agent.run'\n  | 'agent.step'\n  | 'agent.handoff'\n  | 'agent.suspend'\n  | 'agent.resume'\n  | 'provider.generate'\n  | 'provider.stream'\n  | 'tool.execute'\n  | 'tool.approval'\n  | 'memory.read.working'\n  | 'memory.read.session'\n  | 'memory.read.episodic'\n  | 'memory.read.semantic'\n  | 'memory.read.procedural'\n  | 'memory.read.shared'\n  | 'memory.write.working'\n  | 'memory.write.session'\n  | 'memory.write.episodic'\n  | 'memory.write.semantic'\n  | 'memory.write.procedural'\n  | 'memory.write.shared'\n  | 'memory.search.working'\n  | 'memory.search.session'\n  | 'memory.search.episodic'\n  | 'memory.search.semantic'\n  | 'memory.search.procedural'\n  | 'memory.search.shared'\n  | 'memory.consolidate.light'\n  | 'memory.consolidate.standard'\n  | 'memory.consolidate.deep'\n  | 'memory.consolidate.reflect'\n  | 'memory.consolidate.learned-context'\n  | 'memory.search.insight'\n  | 'memory.read.insight'\n  | 'memory.write.insight'\n  | 'memory.conflict'\n  | 'memory.embed'\n  | 'workflow.run'\n  | 'workflow.step'\n  | 'workflow.task'\n  | 'workflow.checkpoint'\n  | 'skill.activate'\n  | 'skill.load'\n  | 'mcp.connect'\n  | 'mcp.call'\n  | 'mcp.list-tools';\n\n/**\n * Status of a finished span. Mirrors the OTel status convention with\n * `'ok' | 'error'` short forms instead of the verbose tristate.\n *\n * @stable\n */\nexport type SpanStatus = 'ok' | 'error' | 'cancelled';\n\n/**\n * Free-form attributes attached to a span.\n *\n * @stable\n */\nexport type SpanAttributes = Readonly<Record<string, SpanAttributeValue>>;\n\n/** @stable */\nexport type SpanAttributeValue =\n  | string\n  | number\n  | boolean\n  | null\n  | ReadonlyArray<string>\n  | ReadonlyArray<number>\n  | ReadonlyArray<boolean>;\n\n/**\n * Typed span. Generic over `SpanType` so consumers can specialize a\n * function on a particular span kind without losing the discriminator.\n *\n * @stable\n */\nexport interface AISpan<T extends SpanType = SpanType> {\n  readonly type: T;\n  readonly id: string;\n  readonly traceId: string;\n  readonly parentId?: string;\n  /** Add or replace attributes. Repeated calls are merged (last write wins). */\n  setAttributes(attrs: SpanAttributes): void;\n  /** Append a span event (attribute-bearing time-stamped marker). */\n  addEvent(name: string, attrs?: SpanAttributes): void;\n  /** Record an exception. Multiple calls are kept in the span event log. */\n  recordException(err: unknown): void;\n  /** Set the terminal status. */\n  setStatus(status: SpanStatus, message?: string): void;\n  /** End the span. Idempotent. */\n  end(): void;\n}\n\n/**\n * Span constructor parameters.\n *\n * @stable\n */\nexport interface StartSpanOptions<T extends SpanType = SpanType> {\n  readonly type: T;\n  readonly attrs?: SpanAttributes;\n  readonly parent?: AISpan;\n}\n\n/**\n * Pluggable tracer. Implementations live in `@graphorin/observability`.\n * The interface intentionally mirrors a subset of the OTel API so that\n * adapter code is a thin pass-through.\n *\n * @stable\n */\nexport interface Tracer {\n  startSpan<T extends SpanType>(opts: StartSpanOptions<T>): AISpan<T>;\n  /**\n   * Convenience wrapper: start a span, run `fn` inside, and call\n   * `setStatus('ok' | 'error')` + `end()` based on the outcome.\n   */\n  span<T extends SpanType, R>(\n    opts: StartSpanOptions<T>,\n    fn: (span: AISpan<T>) => R | Promise<R>,\n  ): Promise<R>;\n  /** Force-flush any pending spans. */\n  shutdown(): Promise<void>;\n}\n\n/**\n * Minimal no-op tracer. Useful as a typed default when downstream code\n * needs a non-null `Tracer` without taking the observability dependency.\n *\n * @stable\n */\nexport const NOOP_TRACER: Tracer = {\n  startSpan<T extends SpanType>(opts: StartSpanOptions<T>): AISpan<T> {\n    const span: AISpan<T> = {\n      type: opts.type,\n      id: '',\n      traceId: '',\n      setAttributes(): void {},\n      addEvent(): void {},\n      recordException(): void {},\n      setStatus(): void {},\n      end(): void {},\n    };\n    return span;\n  },\n  async span<T extends SpanType, R>(\n    opts: StartSpanOptions<T>,\n    fn: (span: AISpan<T>) => R | Promise<R>,\n  ): Promise<R> {\n    const span = this.startSpan(opts);\n    try {\n      return await fn(span);\n    } finally {\n      span.end();\n    }\n  },\n  async shutdown(): Promise<void> {},\n};\n"],"mappings":";;;;;;;AA8IA,MAAaA,cAAsB;CACjC,UAA8B,MAAsC;AAWlE,SAVwB;GACtB,MAAM,KAAK;GACX,IAAI;GACJ,SAAS;GACT,gBAAsB;GACtB,WAAiB;GACjB,kBAAwB;GACxB,YAAkB;GAClB,MAAY;GACb;;CAGH,MAAM,KACJ,MACA,IACY;EACZ,MAAM,OAAO,KAAK,UAAU,KAAK;AACjC,MAAI;AACF,UAAO,MAAM,GAAG,KAAK;YACb;AACR,QAAK,KAAK;;;CAGd,MAAM,WAA0B;CACjC"}
+{"version":3,"file":"tracer.js","names":["NOOP_TRACER: Tracer"],"sources":["../../src/contracts/tracer.ts"],"sourcesContent":["/**\n * Framework-known discriminators for typed observability spans.\n *\n * The list mirrors the span taxonomy documented for the observability\n * layer; concrete implementations live in `@graphorin/observability`.\n * Promoting a frequently-used custom span kind (see\n * {@link CustomSpanType}) into this union is an additive minor change.\n *\n * @stable\n */\nexport type KnownSpanType =\n  | 'agent.run'\n  | 'agent.step'\n  | 'agent.handoff'\n  | 'agent.suspend'\n  | 'agent.resume'\n  | 'provider.generate'\n  | 'provider.stream'\n  | 'tool.execute'\n  | 'tool.approval'\n  | 'memory.read.working'\n  | 'memory.read.session'\n  | 'memory.read.episodic'\n  | 'memory.read.semantic'\n  | 'memory.read.procedural'\n  | 'memory.read.shared'\n  | 'memory.write.working'\n  | 'memory.write.session'\n  | 'memory.write.episodic'\n  | 'memory.write.semantic'\n  | 'memory.write.procedural'\n  | 'memory.write.shared'\n  | 'memory.search.working'\n  | 'memory.search.session'\n  | 'memory.search.episodic'\n  | 'memory.search.semantic'\n  | 'memory.search.procedural'\n  | 'memory.search.shared'\n  | 'memory.consolidate.light'\n  | 'memory.consolidate.standard'\n  | 'memory.consolidate.deep'\n  | 'memory.consolidate.reflect'\n  | 'memory.consolidate.learned-context'\n  | 'memory.search.insight'\n  | 'memory.read.insight'\n  | 'memory.write.insight'\n  | 'memory.conflict'\n  | 'memory.embed'\n  | 'workflow.run'\n  | 'workflow.step'\n  | 'workflow.task'\n  | 'workflow.checkpoint'\n  | 'skill.activate'\n  | 'skill.load'\n  | 'mcp.connect'\n  | 'mcp.call'\n  | 'mcp.list-tools';\n\n/**\n * Namespaced escape hatch for user-defined span kinds (W-126): any\n * string under the `x.` prefix, e.g. `'x.acme.rerank'`. The prefix\n * keeps typo-safety for the known literals - `'memory.serch.semantic'`\n * is still a compile error because it does not start with `x.` -\n * which is why this is a template-literal type and not `string & {}`.\n *\n * Convention: `x.<vendor>.<operation>`. Backends and analytics must\n * tolerate unknown span-type strings (the same policy events already\n * follow). When a custom kind becomes common, promote it into\n * {@link KnownSpanType} (additive minor).\n *\n * @stable\n */\nexport type CustomSpanType = `x.${string}`;\n\n/**\n * Discriminator union for typed observability spans: every\n * {@link KnownSpanType} literal plus the {@link CustomSpanType}\n * namespaced escape. Exhaustive switches over `SpanType` need a\n * default branch for the custom domain.\n *\n * @stable\n */\nexport type SpanType = KnownSpanType | CustomSpanType;\n\n/**\n * Status of a finished span. Mirrors the OTel status convention with\n * `'ok' | 'error'` short forms instead of the verbose tristate.\n *\n * @stable\n */\nexport type SpanStatus = 'ok' | 'error' | 'cancelled';\n\n/**\n * Free-form attributes attached to a span.\n *\n * @stable\n */\nexport type SpanAttributes = Readonly<Record<string, SpanAttributeValue>>;\n\n/** @stable */\nexport type SpanAttributeValue =\n  | string\n  | number\n  | boolean\n  | null\n  | ReadonlyArray<string>\n  | ReadonlyArray<number>\n  | ReadonlyArray<boolean>;\n\n/**\n * W-094: sensitivity opts for {@link AISpan.addEvent}. Event attributes\n * used to be un-taggable, so a default-`'public'` export floor dropped\n * ALL of them - including `exception.type` from `recordException`.\n *\n * @stable\n */\nexport interface AddEventOptions {\n  /** Default tier applied to every attribute of this event. */\n  readonly sensitivity?: import('../types/sensitivity.js').Sensitivity;\n  /** Per-attribute overrides; win over {@link AddEventOptions.sensitivity}. */\n  readonly sensitivityByAttribute?: Readonly<\n    Record<string, import('../types/sensitivity.js').Sensitivity>\n  >;\n}\n\n/**\n * Typed span. Generic over `SpanType` so consumers can specialize a\n * function on a particular span kind without losing the discriminator.\n *\n * @stable\n */\nexport interface AISpan<T extends SpanType = SpanType> {\n  readonly type: T;\n  readonly id: string;\n  readonly traceId: string;\n  readonly parentId?: string;\n  /** Add or replace attributes. Repeated calls are merged (last write wins). */\n  setAttributes(attrs: SpanAttributes): void;\n  /**\n   * Append a span event (attribute-bearing time-stamped marker). The\n   * optional `opts` (W-094) tags the event's attributes with a\n   * sensitivity tier so the validation exporter can pass safe ones\n   * through the default-deny floor - untagged attributes keep being\n   * dropped below the floor.\n   */\n  addEvent(name: string, attrs?: SpanAttributes, opts?: AddEventOptions): void;\n  /** Record an exception. Multiple calls are kept in the span event log. */\n  recordException(err: unknown): void;\n  /** Set the terminal status. */\n  setStatus(status: SpanStatus, message?: string): void;\n  /** End the span. Idempotent. */\n  end(): void;\n}\n\n/**\n * Span constructor parameters.\n *\n * @stable\n */\nexport interface StartSpanOptions<T extends SpanType = SpanType> {\n  readonly type: T;\n  readonly attrs?: SpanAttributes;\n  readonly parent?: AISpan;\n}\n\n/**\n * Pluggable tracer. Implementations live in `@graphorin/observability`.\n * The interface intentionally mirrors a subset of the OTel API so that\n * adapter code is a thin pass-through.\n *\n * @stable\n */\nexport interface Tracer {\n  startSpan<T extends SpanType>(opts: StartSpanOptions<T>): AISpan<T>;\n  /**\n   * Convenience wrapper: start a span, run `fn` inside, and call\n   * `setStatus('ok' | 'error')` + `end()` based on the outcome.\n   */\n  span<T extends SpanType, R>(\n    opts: StartSpanOptions<T>,\n    fn: (span: AISpan<T>) => R | Promise<R>,\n  ): Promise<R>;\n  /** Force-flush any pending spans. */\n  shutdown(): Promise<void>;\n}\n\n/**\n * Minimal no-op tracer. Useful as a typed default when downstream code\n * needs a non-null `Tracer` without taking the observability dependency.\n *\n * @stable\n */\nexport const NOOP_TRACER: Tracer = {\n  startSpan<T extends SpanType>(opts: StartSpanOptions<T>): AISpan<T> {\n    const span: AISpan<T> = {\n      type: opts.type,\n      id: '',\n      traceId: '',\n      setAttributes(): void {},\n      addEvent(): void {},\n      recordException(): void {},\n      setStatus(): void {},\n      end(): void {},\n    };\n    return span;\n  },\n  async span<T extends SpanType, R>(\n    opts: StartSpanOptions<T>,\n    fn: (span: AISpan<T>) => R | Promise<R>,\n  ): Promise<R> {\n    const span = this.startSpan(opts);\n    try {\n      return await fn(span);\n    } finally {\n      span.end();\n    }\n  },\n  async shutdown(): Promise<void> {},\n};\n"],"mappings":";;;;;;;AAgMA,MAAaA,cAAsB;CACjC,UAA8B,MAAsC;AAWlE,SAVwB;GACtB,MAAM,KAAK;GACX,IAAI;GACJ,SAAS;GACT,gBAAsB;GACtB,WAAiB;GACjB,kBAAwB;GACxB,YAAkB;GAClB,MAAY;GACb;;CAGH,MAAM,KACJ,MACA,IACY;EACZ,MAAM,OAAO,KAAK,UAAU,KAAK;AACjC,MAAI;AACF,UAAO,MAAM,GAAG,KAAK;YACb;AACR,QAAK,KAAK;;;CAGd,MAAM,WAA0B;CACjC"}