@namzu/sdk 27.1.0 → 28.0.0

package/dist/types/topic/store.d.ts

@@ -0,0 +1,95 @@
+/**
+ * TopicStore — canonical persistence contract for the Topic layer
+ * (Project → **Topic** → Session → SubSession → Run).
+ *
+ * Topics are pure containers (Phase 0 decision B.1). They have no own
+ * message stream and no fan-in `deriveStatus()` — status is owner-managed
+ * (`'open' | 'archived'`). Every accessor takes explicit {@link TenantId};
+ * cross-tenant access rejects with `TenantIsolationError` (Convention #17).
+ *
+ * Read accessors return `null` when the resource does not exist for the
+ * supplied tenant (deny-by-default surface). Callers branch on missing
+ * explicitly — no fallback substitution.
+ *
+ * `deleteTopic` is intentionally a dumb record-delete at this layer:
+ * it does NOT walk session ownership. The "reject when sessions attached"
+ * precondition lives in {@link import('../../manager/topic/lifecycle.js').TopicManager}
+ * where both stores are in scope. Keeping TopicStore free of cross-store
+ * awareness preserves the single-boundary ownership boundary that Phase 2
+ * has just introduced for this layer (Convention #0).
+ *
+ * NZ-TOPIC-01 renamed this from `ThreadStore`/`createThread` etc, leaving
+ * the `threadId` parameter below alone — it is the FK field a Session
+ * carries to its owning Topic, and that rename had its own data-migration
+ * story (persisted `session.json` records already on disk, see
+ * `store/session/disk.ts`). NZ-TOPIC-03 lands it: the parameter below is
+ * `topicId` now, matching the `Session.topicId` it identifies.
+ */
+import type { Topic } from '../../types/topic/entity.js';
+import type { TenantId } from '../ids/index.js';
+import type { ProjectId, TopicId } from '../session/ids.js';
+/**
+ * Params for {@link TopicStore.createTopic}. The store owns id generation,
+ * `ownerVersion` initialization (0 at create), and timestamps.
+ */
+export interface CreateTopicParams {
+    projectId: ProjectId;
+    /**
+     * User-facing display label. Not unique within the project — see
+     * {@link Topic} JSDoc. Empty strings are permitted; callers that require
+     * a label should validate at the API layer.
+     */
+    title: string;
+}
+/**
+ * Canonical persistence contract for the Topic layer. Every accessor takes
+ * explicit `tenantId`; cross-tenant reads/writes reject with
+ * `TenantIsolationError` (`session/errors.ts`, Convention #17).
+ */
+export interface TopicStore {
+    /**
+     * Persist a new Topic under the given project. Returns the minted
+     * {@link Topic} with `ownerVersion: 0` and freshly-generated
+     * {@link import('../ids/index.js').TopicId}. Callers must ensure the parent
+     * project exists and belongs to the same tenant — the store does not
+     * validate project ownership (that is a cross-store precondition owned by
+     * the manager).
+     */
+    createTopic(params: CreateTopicParams, tenantId: TenantId): Promise<Topic>;
+    /**
+     * Read a Topic by id. Returns `null` when absent. Cross-tenant reads
+     * reject with `TenantIsolationError`.
+     */
+    getTopic(topicId: TopicId, tenantId: TenantId): Promise<Topic | null>;
+    /**
+     * Persist a mutation to a Topic record. CAS on `ownerVersion`: if the
+     * supplied `topic.ownerVersion` does not match the persisted version,
+     * rejects with {@link import('../../session/errors.js').StaleThreadError}
+     * (class name unchanged this release). On success the write commits with
+     * `ownerVersion + 1` and a refreshed `updatedAt`.
+     *
+     * Archival transition (`status: 'open' → 'archived'`) shares this path;
+     * the caller is responsible for verifying that no non-terminal Sessions
+     * are attached before flipping (see TopicManager.archive).
+     */
+    updateTopic(topic: Topic, tenantId: TenantId): Promise<void>;
+    /**
+     * Hard-delete a Topic record. Idempotent — absent topics succeed as a
+     * no-op. Rejects with `TenantIsolationError` on cross-tenant access.
+     *
+     * **Does NOT cascade to child Sessions** — the caller (typically
+     * TopicManager) enforces the precondition that no Sessions reference
+     * this topic. Convention #5: deny-by-default, no implicit cascade.
+     */
+    deleteTopic(topicId: TopicId, tenantId: TenantId): Promise<void>;
+    /**
+     * List all Topics under a project for the given tenant, ordered by
+     * `createdAt` ascending. Returns an empty array when none exist.
+     * Cross-tenant reads reject with `TenantIsolationError`.
+     *
+     * The return shape is a concrete snapshot — callers that mutate the
+     * result array do not affect store state.
+     */
+    listTopics(projectId: ProjectId, tenantId: TenantId): Promise<readonly Topic[]>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/types/topic/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/types/topic/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAA;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,SAAS,EAAE,SAAS,CAAA;IACpB;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IAC1B;;;;;;;OAOG;IACH,WAAW,CAAC,MAAM,EAAE,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IAE1E;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;IAErE;;;;;;;;;;OAUG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5D;;;;;;;OAOG;IACH,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEhE;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,KAAK,EAAE,CAAC,CAAA;CAC/E"}

package/dist/types/topic/store.js

@@ -0,0 +1,29 @@
+/**
+ * TopicStore — canonical persistence contract for the Topic layer
+ * (Project → **Topic** → Session → SubSession → Run).
+ *
+ * Topics are pure containers (Phase 0 decision B.1). They have no own
+ * message stream and no fan-in `deriveStatus()` — status is owner-managed
+ * (`'open' | 'archived'`). Every accessor takes explicit {@link TenantId};
+ * cross-tenant access rejects with `TenantIsolationError` (Convention #17).
+ *
+ * Read accessors return `null` when the resource does not exist for the
+ * supplied tenant (deny-by-default surface). Callers branch on missing
+ * explicitly — no fallback substitution.
+ *
+ * `deleteTopic` is intentionally a dumb record-delete at this layer:
+ * it does NOT walk session ownership. The "reject when sessions attached"
+ * precondition lives in {@link import('../../manager/topic/lifecycle.js').TopicManager}
+ * where both stores are in scope. Keeping TopicStore free of cross-store
+ * awareness preserves the single-boundary ownership boundary that Phase 2
+ * has just introduced for this layer (Convention #0).
+ *
+ * NZ-TOPIC-01 renamed this from `ThreadStore`/`createThread` etc, leaving
+ * the `threadId` parameter below alone — it is the FK field a Session
+ * carries to its owning Topic, and that rename had its own data-migration
+ * story (persisted `session.json` records already on disk, see
+ * `store/session/disk.ts`). NZ-TOPIC-03 lands it: the parameter below is
+ * `topicId` now, matching the `Session.topicId` it identifies.
+ */
+export {};
+//# sourceMappingURL=store.js.map

package/dist/types/topic/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../src/types/topic/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/types/workspace/ref.d.ts

@@ -37,6 +37,13 @@ export type WorkspaceBackendMeta = GitWorktreeBackendMeta;
  * Persisted ref to a provisioned workspace. Every {@link Session} with a
  * running Run persists a {@link WorkspaceRef} so recovery after process
  * restart is possible (session-hierarchy.md §7.1).
+ *
+ * NOT `Project.rootPath`. This is per-RUN provisioning — a git worktree cut
+ * for one run and discarded after it, which may be a different directory
+ * entirely. `Project.rootPath` is the durable binding a host uses to answer
+ * "which project is this directory" across sessions and process restarts.
+ * The two words are close enough that the distinction has been rediscovered
+ * more than once; it is written here so it does not have to be again.
  */
 export interface WorkspaceRef {
     id: WorkspaceId;

package/dist/types/workspace/ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../src/types/workspace/ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAA;AAEpF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,cAAc,CAAA;IACvB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,CAAA;AAEzD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,WAAW,CAAA;IACf,IAAI,EAAE,oBAAoB,CAAA;IAC1B,SAAS,EAAE,IAAI,CAAA;CACf"}
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../../src/types/workspace/ref.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAA;AAEpF;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,cAAc,CAAA;IACvB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,CAAA;AAEzD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,WAAW,CAAA;IACf,IAAI,EAAE,oBAAoB,CAAA;IAC1B,SAAS,EAAE,IAAI,CAAA;CACf"}

package/dist/utils/abort.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKnE;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA4BnF"}
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAoBnE;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CA4BnF"}

package/dist/utils/abort.js

@@ -27,8 +27,20 @@ import { toErrorMessage } from './error.js';
 export function abortReasonText(reason) {
     if (!(reason instanceof Error))
         return undefined;
-    if (reason.name === 'AbortError' || reason.name === 'TimeoutError')
+    // `RunCancelled` carries a machine-readable CAUSE ('user' | 'parent' |
+    // 'budget' | 'hook'), and rendering it here would print "was cancelled:
+    // run cancelled by parent" — the same noise the two names above are
+    // suppressed for. A reader wanting the cause asks `cancelCauseOf`.
+    //
+    // By name, not by class, for the reason this whole function is: a reason
+    // crosses a package boundary where `instanceof` stops holding across
+    // duplicate copies. Importing the class here would also close a cycle
+    // between `utils/` and `types/run/`.
+    if (reason.name === 'AbortError' ||
+        reason.name === 'TimeoutError' ||
+        reason.name === 'RunCancelled') {
         return undefined;
+    }
     const text = toErrorMessage(reason).trim();
     return text.length > 0 ? text : undefined;
 }

package/dist/utils/abort.js.map

@@ -1 +1 @@
-{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC9C,IAAI,CAAC,CAAC,MAAM,YAAY,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAChD,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY,IAAI,MAAM,CAAC,IAAI,KAAK,cAAc;QAAE,OAAO,SAAS,CAAA;IACpF,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAuB;IACjE,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAA;IAEnC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjC,OAAO,KAAK,CAAA;IACb,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAEpC,MAAM,aAAa,GAAG,GAAS,EAAE;QAChC,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,CAAA;QAC7B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAChC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAChC,CAAC;IACF,CAAC,CAAA;IAED,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtE,KAAK,CAAC,MAAM,CAAC,gBAAgB,CAC5B,OAAO,EACP,GAAG,EAAE;QACJ,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IAC1D,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACd,CAAA;IAED,OAAO,KAAK,CAAA;AACb,CAAC"}
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../../src/utils/abort.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,MAAe;IAC9C,IAAI,CAAC,CAAC,MAAM,YAAY,KAAK,CAAC;QAAE,OAAO,SAAS,CAAA;IAChD,uEAAuE;IACvE,wEAAwE;IACxE,oEAAoE;IACpE,mEAAmE;IACnE,EAAE;IACF,yEAAyE;IACzE,qEAAqE;IACrE,sEAAsE;IACtE,qCAAqC;IACrC,IACC,MAAM,CAAC,IAAI,KAAK,YAAY;QAC5B,MAAM,CAAC,IAAI,KAAK,cAAc;QAC9B,MAAM,CAAC,IAAI,KAAK,cAAc,EAC7B,CAAC;QACF,OAAO,SAAS,CAAA;IACjB,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;IAC1C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAuB;IACjE,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAA;IAEnC,IAAI,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjC,OAAO,KAAK,CAAA;IACb,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;IAEpC,MAAM,aAAa,GAAG,GAAS,EAAE;QAChC,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,CAAA;QAC7B,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YAChC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QAChC,CAAC;IACF,CAAC,CAAA;IAED,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAEtE,KAAK,CAAC,MAAM,CAAC,gBAAgB,CAC5B,OAAO,EACP,GAAG,EAAE;QACJ,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;IAC1D,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACd,CAAA;IAED,OAAO,KAAK,CAAA;AACb,CAAC"}

package/dist/utils/hash.d.ts

@@ -5,4 +5,14 @@ export declare function buildToolResultHashes(toolResults: Array<{
     input: unknown;
     output: string;
 }>): Record<string, string>;
+/**
+ * A short, stable digest of any JSON-able value.
+ *
+ * `JSON.stringify` is not stable across key insertion order, so callers
+ * that need two equal-by-content values to hash alike must normalise
+ * first. The one caller that does — the request envelope — sorts its tool
+ * list before hashing, because the ORDER of the tool array is itself part
+ * of what the model sees and a re-ordered catalogue is a real change.
+ */
+export declare function stableDigest(value: unknown): string;
 //# sourceMappingURL=hash.d.ts.map

package/dist/utils/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAEA,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGvF;AAED,wBAAgB,qBAAqB,CACpC,WAAW,EAAE,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1F,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAEA,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGvF;AAED,wBAAgB,qBAAqB,CACpC,WAAW,EAAE,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1F,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAKnD"}

package/dist/utils/hash.js

@@ -10,4 +10,19 @@ export function buildToolResultHashes(toolResults) {
     }
     return hashes;
 }
+/**
+ * A short, stable digest of any JSON-able value.
+ *
+ * `JSON.stringify` is not stable across key insertion order, so callers
+ * that need two equal-by-content values to hash alike must normalise
+ * first. The one caller that does — the request envelope — sorts its tool
+ * list before hashing, because the ORDER of the tool array is itself part
+ * of what the model sees and a re-ordered catalogue is a real change.
+ */
+export function stableDigest(value) {
+    return createHash('sha256')
+        .update(JSON.stringify(value) ?? 'null')
+        .digest('hex')
+        .slice(0, 16);
+}
 //# sourceMappingURL=hash.js.map

package/dist/utils/hash.js.map

@@ -1 +1 @@
-{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,KAAc,EAAE,MAAc;IAC9E,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;IACxD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACpE,CAAC;AAED,MAAM,UAAU,qBAAqB,CACpC,WAA4F;IAE5F,MAAM,MAAM,GAA2B,EAAE,CAAA;IACzC,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACzF,CAAC;IACD,OAAO,MAAM,CAAA;AACd,CAAC"}
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/utils/hash.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,KAAc,EAAE,MAAc;IAC9E,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;IACxD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACpE,CAAC;AAED,MAAM,UAAU,qBAAqB,CACpC,WAA4F;IAE5F,MAAM,MAAM,GAA2B,EAAE,CAAA;IACzC,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACzF,CAAC;IACD,OAAO,MAAM,CAAA;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC;SACzB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;SACvC,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;AACf,CAAC"}

package/dist/utils/id.d.ts

@@ -1,6 +1,14 @@
-import type { ActivityId, AdvisoryCallId, AdvisoryId, CheckpointId, ChunkId, ConnectorId, ConnectorInstanceId, CredentialId, DeliverableId, DocumentId, EmergencySaveId, EnvironmentId, ExecutionContextId, HandoffId, KnowledgeBaseId, MCPClientId, MCPServerId, MCPSessionId, MemoryId, MessageId, PlanId, PluginId, ProjectId, RunId, SandboxId, SessionId, SubSessionId, SummaryId, TaskId, TenantId, ThreadId, ToolCallId, WorkspaceId } from '../types/ids/index.js';
+import type { ActivityId, AdvisoryCallId, AdvisoryId, AgentId, AuditEventId, CheckpointId, ChunkId, ConnectorId, ConnectorInstanceId, CredentialId, DeliverableId, DocumentId, EmergencySaveId, EnvironmentId, ExecutionContextId, HandoffId, KnowledgeBaseId, KnowledgeBaseRef, LockId, MCPClientId, MCPServerId, MCPSessionId, MemoryId, MemoryStoreRef, MessageId, PlanId, PluginId, ProjectId, RunId, SandboxId, SessionId, SubSessionId, SummaryId, TaskId, TenantId, ToolCallId, TopicId, UserId, VaultRef, WorkspaceId } from '../types/ids/index.js';
 export declare function generateProjectId(): ProjectId;
-export declare function generateThreadId(): ThreadId;
+export declare function generateTopicId(): TopicId;
+/**
+ * @deprecated Use {@link generateTopicId}. Removal is NZ-TOPIC-05.
+ *
+ * Mints `top_` from NZ-TOPIC-04 on — an alias that kept minting `thd_`
+ * would hand two different id spaces to one program depending on which
+ * name the caller happened to import.
+ */
+export declare const generateThreadId: typeof generateTopicId;
 export declare function generateRunId(): RunId;
 export declare function generateMessageId(): MessageId;
 export declare function generateSessionId(): SessionId;
@@ -23,6 +31,7 @@ export declare function generateEnvironmentId(): EnvironmentId;
 export declare function generateCheckpointId(): CheckpointId;
 export declare function generateAdvisoryId(): AdvisoryId;
 export declare function generateAdvisoryCallId(): AdvisoryCallId;
+export declare function generateAuditEventId(): AuditEventId;
 export declare function generateEmergencySaveId(): EmergencySaveId;
 export declare function generateMemoryId(): MemoryId;
 export declare function generatePluginId(): PluginId;
@@ -37,4 +46,83 @@ export declare function parseRunId(raw: string): RunId;
 export declare function parseConnectorInstanceId(raw: string): ConnectorInstanceId;
 export declare function parsePluginId(raw: string): PluginId;
 export declare function parseSandboxId(raw: string): SandboxId;
+/** A string that does not carry the prefix the id type requires. */
+export declare class InvalidIdError extends Error {
+    readonly value: string;
+    readonly expectedPrefix: string;
+    constructor(value: string, expectedPrefix: string);
+}
+/**
+ * Builds one prefix check.
+ *
+ * Throws rather than returning `undefined`, per `refuse-do-not-degrade`: a
+ * caller holding a malformed id has no correct fallback available, and the
+ * value is on its way to becoming a store key. Returning the input
+ * unchanged on the happy path is also load-bearing — a constructor that
+ * allocated a copy would silently break `===` on ids used as map keys.
+ *
+ * The trailing underscore in every prefix is what makes them unambiguous:
+ * `mcpc_x` does not start with `mcp_`, and `advc_x` does not start with
+ * `adv_`, so no id type can swallow another's values.
+ */
+/**
+ * What a checked constructor is, named so the id type can be supplied by
+ * ANNOTATION rather than as a type argument.
+ *
+ * That distinction is load-bearing and was got wrong once. `makeIdParser<
+ * RunId>('ses_')` compiles: supplying one of two type parameters explicitly
+ * makes the other fall back to its DEFAULT rather than be inferred, so `P`
+ * became `string`, the constraint read `RunId extends string`, and the
+ * prefix check evaporated. Caught by mutating `asRunId`'s prefix and finding
+ * the build still green — a check that cannot fail. With the type on the
+ * const instead, `T` comes from the contextual type and `P` is inferred from
+ * the argument, so the same mutation is a compile error.
+ */
+type IdParser<T extends string> = (value: string) => T;
+export declare const asRunId: IdParser<RunId>;
+export declare const asMessageId: IdParser<MessageId>;
+export declare const asSessionId: IdParser<SessionId>;
+export declare const asToolCallId: IdParser<ToolCallId>;
+export declare const asActivityId: IdParser<ActivityId>;
+export declare const asTaskId: IdParser<TaskId>;
+export declare const asPlanId: IdParser<PlanId>;
+export declare const asKnowledgeBaseId: IdParser<KnowledgeBaseId>;
+export declare const asDocumentId: IdParser<DocumentId>;
+export declare const asChunkId: IdParser<ChunkId>;
+export declare const asConnectorId: IdParser<ConnectorId>;
+export declare const asConnectorInstanceId: IdParser<ConnectorInstanceId>;
+export declare const asTenantId: IdParser<TenantId>;
+export declare const asCredentialId: IdParser<CredentialId>;
+export declare const asExecutionContextId: IdParser<ExecutionContextId>;
+export declare const asMCPServerId: IdParser<MCPServerId>;
+export declare const asMCPClientId: IdParser<MCPClientId>;
+export declare const asMCPSessionId: IdParser<MCPSessionId>;
+export declare const asEnvironmentId: IdParser<EnvironmentId>;
+export declare const asCheckpointId: IdParser<CheckpointId>;
+export declare const asLockId: IdParser<LockId>;
+export declare const asAdvisoryId: IdParser<AdvisoryId>;
+export declare const asAdvisoryCallId: IdParser<AdvisoryCallId>;
+export declare const asEmergencySaveId: IdParser<EmergencySaveId>;
+export declare const asMemoryId: IdParser<MemoryId>;
+export declare const asPluginId: IdParser<PluginId>;
+export declare const asSandboxId: IdParser<SandboxId>;
+export declare const asAuditEventId: IdParser<AuditEventId>;
+export declare const asUserId: IdParser<UserId>;
+/**
+ * @deprecated Nothing in this kernel mints an `agt_` id, so this constructor
+ * throws on every agent identifier the kernel actually produces — an agent is
+ * named by its registry key. See {@link AgentId}. Removal is a later major.
+ */
+export declare const asAgentId: IdParser<AgentId>;
+export declare const asMemoryStoreRef: IdParser<MemoryStoreRef>;
+export declare const asVaultRef: IdParser<VaultRef>;
+export declare const asKnowledgeBaseRef: IdParser<KnowledgeBaseRef>;
+export declare const asProjectId: IdParser<ProjectId>;
+export declare const asTopicId: IdParser<TopicId>;
+export declare const asSubSessionId: IdParser<SubSessionId>;
+export declare const asHandoffId: IdParser<HandoffId>;
+export declare const asWorkspaceId: IdParser<WorkspaceId>;
+export declare const asSummaryId: IdParser<SummaryId>;
+export declare const asDeliverableId: IdParser<DeliverableId>;
+export {};
 //# sourceMappingURL=id.d.ts.map

package/dist/utils/id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACX,UAAU,EACV,cAAc,EACd,UAAU,EACV,YAAY,EACZ,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,aAAa,EACb,UAAU,EACV,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,eAAe,EACf,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,MAAM,EACN,QAAQ,EACR,SAAS,EACT,KAAK,EACL,SAAS,EACT,SAAS,EACT,YAAY,EACZ,SAAS,EACT,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,UAAU,EACV,WAAW,EACX,MAAM,uBAAuB,CAAA;AAsB9B,wBAAgB,iBAAiB,IAAI,SAAS,CAE7C;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAE3C;AAED,wBAAgB,aAAa,IAAI,KAAK,CAErC;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CAE7C;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CAE7C;AAED,wBAAgB,kBAAkB,IAAI,UAAU,CAE/C;AAED,wBAAgB,kBAAkB,IAAI,UAAU,CAE/C;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,uBAAuB,IAAI,eAAe,CAEzD;AAED,wBAAgB,kBAAkB,IAAI,UAAU,CAE/C;AAED,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,wBAAgB,mBAAmB,IAAI,WAAW,CAEjD;AAED,wBAAgB,2BAA2B,IAAI,mBAAmB,CAEjE;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAE3C;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CAEnD;AAED,wBAAgB,0BAA0B,IAAI,kBAAkB,CAE/D;AAED,wBAAgB,mBAAmB,IAAI,WAAW,CAEjD;AAED,wBAAgB,mBAAmB,IAAI,WAAW,CAEjD;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CAEnD;AAED,wBAAgB,qBAAqB,IAAI,aAAa,CAErD;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CAEnD;AAED,wBAAgB,kBAAkB,IAAI,UAAU,CAE/C;AAED,wBAAgB,sBAAsB,IAAI,cAAc,CAEvD;AAED,wBAAgB,uBAAuB,IAAI,eAAe,CAEzD;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAE3C;AAED,wBAAgB,gBAAgB,IAAI,QAAQ,CAE3C;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CAE7C;AAED,wBAAgB,mBAAmB,IAAI,WAAW,CAEjD;AAED,wBAAgB,oBAAoB,IAAI,YAAY,CAEnD;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CAE7C;AAED,wBAAgB,iBAAiB,IAAI,SAAS,CAE7C;AAED,wBAAgB,qBAAqB,IAAI,aAAa,CAErD;AASD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAErD;AACD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,CAE7C;AACD,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAEzE;AACD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAEnD;AACD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAErD"}
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"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"}

package/dist/utils/id.js

@@ -1,7 +1,23 @@
 import { randomBytes } from 'node:crypto';
+import { unsafeId } from '../types/ids/brand.js';
 const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
 const ALPHABET_LEN = ALPHABET.length;
 const MAX_UNIFORM_BYTE = Math.floor(256 / ALPHABET_LEN) * ALPHABET_LEN;
+/**
+ * Mints an id, with the PREFIX checked against the id's own type.
+ *
+ * The two type parameters are what keeps that check alive now the ids are
+ * nominal (NZ-SURF-11). `T` is inferred from the caller's declared return
+ * type, `P` from the literal prefix, and the constraint `T extends
+ * `${P}${string}`` is what makes `generateRunId` unable to return
+ * `generateId('ses_')`: a branded `RunId` is assignable to `` `run_${string}` ``
+ * but not to `` `ses_${string}` ``, so the wrong prefix fails to compile.
+ *
+ * Without the constraint the brand would have COST a check — `unsafeId<T>`
+ * accepts any string, so `T` alone would let every generator mint any
+ * prefix. That is the docker `sandbox_`/`sbx_` defect, one layer up, which
+ * is why this is written the awkward way rather than the short way.
+ */
 function generateId(prefix, length = 12) {
     let suffix = '';
     let remaining = length;
@@ -16,14 +32,22 @@ function generateId(prefix, length = 12) {
             }
         }
     }
-    return `${prefix}${suffix}`;
+    return unsafeId(`${prefix}${suffix}`);
 }
 export function generateProjectId() {
     return generateId('prj_');
 }
-export function generateThreadId() {
-    return generateId('thd_');
-}
+export function generateTopicId() {
+    return generateId('top_');
+}
+/**
+ * @deprecated Use {@link generateTopicId}. Removal is NZ-TOPIC-05.
+ *
+ * Mints `top_` from NZ-TOPIC-04 on — an alias that kept minting `thd_`
+ * would hand two different id spaces to one program depending on which
+ * name the caller happened to import.
+ */
+export const generateThreadId = generateTopicId;
 export function generateRunId() {
     return generateId('run_');
 }
@@ -90,6 +114,9 @@ export function generateAdvisoryId() {
 export function generateAdvisoryCallId() {
     return generateId('advc_');
 }
+export function generateAuditEventId() {
+    return generateId('aud_');
+}
 export function generateEmergencySaveId() {
     return generateId('esave_');
 }
@@ -121,7 +148,7 @@ function parseId(raw, prefix, typeName) {
     if (!raw.startsWith(prefix)) {
         throw new Error(`Invalid ${typeName}: expected "${prefix}" prefix, got "${raw}"`);
     }
-    return raw;
+    return unsafeId(raw);
 }
 export function parseProjectId(raw) {
     return parseId(raw, 'prj_', 'ProjectId');
@@ -138,4 +165,85 @@ export function parsePluginId(raw) {
 export function parseSandboxId(raw) {
     return parseId(raw, 'sbx_', 'SandboxId');
 }
+// ─── validating constructors ─────────────────────────────────────────────
+//
+// There is no runtime prefix check anywhere in this tree. The 700-odd
+// `as RunId` casts in it assert without verifying, so a `ses_` value cast to
+// `RunId` reaches a store key unremarked and the first sign of it is a
+// lookup that finds nothing.
+//
+// These are the check. One per id type rather than a single generic
+// `asId(prefix, value)`, and the repetition is the point: a generic loses
+// the return type, so the call site stops type-checking and the whole
+// exercise buys nothing. The implementations are one function.
+/** A string that does not carry the prefix the id type requires. */
+export class InvalidIdError extends Error {
+    value;
+    expectedPrefix;
+    constructor(value, expectedPrefix) {
+        super(`Not a valid id: ${JSON.stringify(value)} does not start with ${JSON.stringify(expectedPrefix)}. Ids are minted by the matching generate*Id() factory; a literal from a log or a URL has to be checked before it is used as one.`);
+        this.value = value;
+        this.expectedPrefix = expectedPrefix;
+        this.name = 'InvalidIdError';
+    }
+}
+function makeIdParser(prefix) {
+    return (value) => {
+        if (!value.startsWith(prefix))
+            throw new InvalidIdError(value, prefix);
+        return unsafeId(value);
+    };
+}
+export const asRunId = makeIdParser('run_');
+export const asMessageId = makeIdParser('msg_');
+export const asSessionId = makeIdParser('ses_');
+export const asToolCallId = makeIdParser('call_');
+export const asActivityId = makeIdParser('act_');
+export const asTaskId = makeIdParser('task_');
+export const asPlanId = makeIdParser('plan_');
+export const asKnowledgeBaseId = makeIdParser('kb_');
+export const asDocumentId = makeIdParser('doc_');
+export const asChunkId = makeIdParser('chk_');
+export const asConnectorId = makeIdParser('conn_');
+export const asConnectorInstanceId = makeIdParser('ci_');
+export const asTenantId = makeIdParser('tnt_');
+export const asCredentialId = makeIdParser('cred_');
+export const asExecutionContextId = makeIdParser('ectx_');
+export const asMCPServerId = makeIdParser('mcp_');
+export const asMCPClientId = makeIdParser('mcpc_');
+export const asMCPSessionId = makeIdParser('mcps_');
+export const asEnvironmentId = makeIdParser('env_');
+export const asCheckpointId = makeIdParser('cp_');
+export const asLockId = makeIdParser('lock_');
+export const asAdvisoryId = makeIdParser('adv_');
+export const asAdvisoryCallId = makeIdParser('advc_');
+export const asEmergencySaveId = makeIdParser('esave_');
+export const asMemoryId = makeIdParser('mem_');
+export const asPluginId = makeIdParser('plg_');
+export const asSandboxId = makeIdParser('sbx_');
+export const asAuditEventId = makeIdParser('aud_');
+export const asUserId = makeIdParser('usr_');
+/**
+ * @deprecated Nothing in this kernel mints an `agt_` id, so this constructor
+ * throws on every agent identifier the kernel actually produces — an agent is
+ * named by its registry key. See {@link AgentId}. Removal is a later major.
+ */
+export const asAgentId = makeIdParser('agt_');
+export const asMemoryStoreRef = makeIdParser('mms_');
+export const asVaultRef = makeIdParser('vlt_');
+export const asKnowledgeBaseRef = makeIdParser('kbs_');
+export const asProjectId = makeIdParser('prj_');
+export const asTopicId = makeIdParser('top_');
+export const asSubSessionId = makeIdParser('sub_');
+export const asHandoffId = makeIdParser('hof_');
+export const asWorkspaceId = makeIdParser('wsp_');
+export const asSummaryId = makeIdParser('sum_');
+export const asDeliverableId = makeIdParser('del_');
+// No `asThreadId`, deliberately. `ThreadId` is an alias of `TopicId` from
+// the Topic rename, so `asTopicId` already accepts every value one can hold
+// — and a parser shipped `@deprecated` on the day it is written is a name
+// that exists only to be removed. `declared-but-undriven`.
+// `ToolUseId` is a bare `string` — it comes from a provider, which chooses
+// its own shape, so there is no prefix to check and a constructor here would
+// be a check that cannot fail.
 //# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -1 +1 @@
-{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":"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"}

package/dist/utils/log/attributes.d.ts

@@ -0,0 +1,17 @@
+type AttributeValue = string | number | boolean | readonly (string | number | boolean)[];
+type AttributeKey = `namzu.${string}` | `gen_ai.${string}` | `service.${string}` | `exception.${string}`;
+/**
+ * A namespaced, shape-safe attribute bag. Deliberately NOT
+ * `Partial<Record<...>>`: `Partial` would type every property as
+ * `AttributeValue | undefined`, and this repo's tsconfig does not set
+ * `exactOptionalPropertyTypes` — so a `Partial` version would let
+ * `{ 'namzu.x.y': undefined }` compile, an attribute that is present and
+ * holds nothing. Plain `Record` over a template-literal key domain does not
+ * require every possible key to appear — there is no finite set of keys to
+ * require — so dropping `Partial` costs a caller nothing: it still supplies
+ * only the keys it has, and gains that an explicit `undefined` is rejected
+ * the same way `null` and a nested object already are.
+ */
+export type LogAttributes = Readonly<Record<AttributeKey, AttributeValue>>;
+export {};
+//# sourceMappingURL=attributes.d.ts.map

package/dist/utils/log/attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.d.ts","sourceRoot":"","sources":["../../../src/utils/log/attributes.ts"],"names":[],"mappings":"AA0BA,KAAK,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,CAAA;AAExF,KAAK,YAAY,GACd,SAAS,MAAM,EAAE,GACjB,UAAU,MAAM,EAAE,GAClB,WAAW,MAAM,EAAE,GACnB,aAAa,MAAM,EAAE,CAAA;AAExB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,cAAc,CAAC,CAAC,CAAA"}

package/dist/utils/log/attributes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attributes.js.map

package/dist/utils/log/attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attributes.js","sourceRoot":"","sources":["../../../src/utils/log/attributes.ts"],"names":[],"mappings":""}

package/dist/utils/log/caps.d.ts

@@ -0,0 +1,27 @@
+import type { LogRecord, MutableLogSinkCounters } from './types.js';
+export declare const MAX_ATTRIBUTES = 64;
+export declare const MAX_VALUE_BYTES: number;
+export declare const MAX_RECORD_BYTES: number;
+/**
+ * At most 64 attributes. Excess keys are dropped in ascending key order —
+ * the same deterministic rule `capTotalSize` uses below, so a reader who has
+ * learned one learns both.
+ */
+export declare function capAttributeCount(record: LogRecord, counters: MutableLogSinkCounters): LogRecord;
+/**
+ * Each string attribute value truncated at 8 KiB, tail replaced by
+ * `…[truncated N bytes]` inside the value — self-describing, so no extra
+ * flag field is minted for something the value already says about itself.
+ */
+export declare function truncateValues(record: LogRecord, counters: MutableLogSinkCounters): LogRecord;
+/**
+ * Total serialized record ≤ 16 KiB. Per-value and per-count caps are
+ * independently satisfiable by a record with many small attributes, so this
+ * is the last line and measures the whole record, not one dimension of it.
+ * Attributes are dropped in ascending key order until it fits, and
+ * `namzu.log.truncated = true` is set on what remains — the marker a
+ * downstream reader needs to tell "this record is smaller than what was
+ * logged" from "this is genuinely all there was".
+ */
+export declare function capTotalSize(record: LogRecord, counters: MutableLogSinkCounters): LogRecord;
+//# sourceMappingURL=caps.d.ts.map

package/dist/utils/log/caps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"caps.d.ts","sourceRoot":"","sources":["../../../src/utils/log/caps.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAEnE,eAAO,MAAM,cAAc,KAAK,CAAA;AAChC,eAAO,MAAM,eAAe,QAAW,CAAA;AACvC,eAAO,MAAM,gBAAgB,QAAY,CAAA;AAEzC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,sBAAsB,GAAG,SAAS,CAchG;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,sBAAsB,GAAG,SAAS,CAkB7F;AAsBD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,sBAAsB,GAAG,SAAS,CAqB3F"}