@lssm/lib.contracts-spec 17.3.2

package/dist/rich-reference/index.js

@@ -0,0 +1,19 @@
+export{toAgentJson,toAgentJsonBatch}from"./agent-export.js";export{canonicalJsonString,serializeRichReference,serializeRichReferenceBatch}from"./canonical-serializer.js";export{defineReferenceKind}from"./define-kind.js";export{DENIAL_TOKEN_PREFIX,looksLikeDenialToken}from"./denial-token-shape.js";export*from"./kinds/index.js";export{defaultCopyMarkdownHandler,fromMarkdown,toMarkdown}from"./markdown-envelope.js";export{applyKindRedaction}from"./redaction.js";export{clearReferenceKindRegistry,getKind,listKinds,registerKind,tryGetKind,unregisterKind}from"./registry.js";export{asReferenceInstanceId,asReferenceKindId}from"./types.js";export const richReferenceGoalDoc={id:"docs.contracts-spec.rich-reference.goal",title:"RichReference goal",summary:"One canonical, governance-aware reference type across all surfaces.",kind:"goal",visibility:"public",route:"/docs/contracts-spec/rich-reference/goal",tags:["rich-reference","governance","contracts-spec"],body:`# RichReference
+
+RichReference is the canonical transport for governed, kind-typed references that travel through REST, GraphQL, MCP, and agent surfaces. Each kind declares its payload schema and the subset of fields that may carry sensitive data; the runtime (S-2) enforces post-handler redaction using HMAC-signed denial tokens (F-5 mitigation).`};export const richReferenceUsageDoc={id:"docs.contracts-spec.rich-reference.usage",title:"RichReference usage",summary:"Authoring kinds and wiring governance ports.",kind:"usage",visibility:"public",route:"/docs/contracts-spec/rich-reference/usage",tags:["rich-reference","authoring"],body:`# Authoring a reference kind
+
+\`\`\`ts
+import { defineReferenceKind } from '@lssm/lib.contracts-spec/rich-reference';
+import { z } from 'zod';
+
+export const ticketKind = defineReferenceKind({
+  id: 'ticket',
+  schema: z.object({ id: z.string(), title: z.string() }),
+  sensitiveFields: ['title'],
+  defaultPreview: 'inline-card',
+  defaultPanel: 'drawer',
+  icon: 'ticket',
+});
+\`\`\`
+
+\`sensitiveFields\` is required at the type level and at runtime; kinds with no sensitive fields MUST pass \`[]\` with an inline confirmation comment (F-4 mitigation).`};

package/dist/rich-reference/kinds/code-symbol.d.js

@@ -0,0 +1 @@
+export{};

package/dist/rich-reference/kinds/code-symbol.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Built-in `code-symbol` reference kind.
+ *
+ * Represents a named code symbol resolvable to a workspace location. `path`,
+ * `signature`, and `snippet` may carry proprietary source; declared
+ * sensitive.
+ */
+import { z } from 'zod';
+declare const CodeSymbolPayloadSchema: z.ZodObject<{
+    language: z.ZodString;
+    symbol: z.ZodString;
+    kind: z.ZodOptional<z.ZodEnum<{
+        class: "class";
+        constant: "constant";
+        function: "function";
+        interface: "interface";
+        method: "method";
+        other: "other";
+        type: "type";
+        variable: "variable";
+    }>>;
+    path: z.ZodOptional<z.ZodString>;
+    startLine: z.ZodOptional<z.ZodNumber>;
+    endLine: z.ZodOptional<z.ZodNumber>;
+    signature: z.ZodOptional<z.ZodString>;
+    snippet: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CodeSymbolPayload = z.infer<typeof CodeSymbolPayloadSchema>;
+export declare const codeSymbolKind: import("..").ReferenceKindDefinition<{
+    language: string;
+    symbol: string;
+    kind?: "class" | "constant" | "function" | "interface" | "method" | "other" | "type" | "variable" | undefined;
+    path?: string | undefined;
+    startLine?: number | undefined;
+    endLine?: number | undefined;
+    signature?: string | undefined;
+    snippet?: string | undefined;
+}>;
+export {};

package/dist/rich-reference/kinds/code-symbol.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{defineReferenceKind as n}from"../define-kind.js";const o=e.object({language:e.string().min(1),symbol:e.string().min(1),kind:e.enum(["function","method","class","interface","type","constant","variable","other"]).optional(),path:e.string().optional(),startLine:e.number().int().nonnegative().optional(),endLine:e.number().int().nonnegative().optional(),signature:e.string().optional(),snippet:e.string().optional()});export const codeSymbolKind=n({id:"code-symbol",schema:o,sensitiveFields:["path","signature","snippet"],defaultPreview:"inline-chip",defaultPanel:"drawer",icon:"code"});

package/dist/rich-reference/kinds/database-record.d.js

@@ -0,0 +1 @@
+export{};

package/dist/rich-reference/kinds/database-record.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Built-in `database-record` reference kind.
+ *
+ * Represents one row in a governed schema (database/schema/table/primary key).
+ * `naturalKey` and `displayValue` may carry tenant- or row-level PII and are
+ * declared as `sensitiveFields`; RoleMorph (S-3) and per-row handlers (S-3)
+ * decide redaction per (kindId, subject).
+ */
+import { z } from 'zod';
+declare const DatabaseRecordPayloadSchema: z.ZodObject<{
+    databaseKey: z.ZodString;
+    schemaKey: z.ZodString;
+    tableName: z.ZodString;
+    primaryKey: z.ZodString;
+    naturalKey: z.ZodOptional<z.ZodString>;
+    displayValue: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DatabaseRecordPayload = z.infer<typeof DatabaseRecordPayloadSchema>;
+export declare const databaseRecordKind: import("..").ReferenceKindDefinition<{
+    databaseKey: string;
+    schemaKey: string;
+    tableName: string;
+    primaryKey: string;
+    naturalKey?: string | undefined;
+    displayValue?: string | undefined;
+    url?: string | undefined;
+}>;
+export {};

package/dist/rich-reference/kinds/database-record.js

@@ -0,0 +1 @@
+import{z as a}from"zod";import{defineReferenceKind as e}from"../define-kind.js";const t=a.object({databaseKey:a.string().min(1),schemaKey:a.string().min(1),tableName:a.string().min(1),primaryKey:a.string().min(1),naturalKey:a.string().optional(),displayValue:a.string().optional(),url:a.string().url().optional()});export const databaseRecordKind=e({id:"database-record",schema:t,sensitiveFields:["naturalKey","displayValue"],defaultPreview:"inline-card",defaultPanel:"drawer",icon:"database"});

package/dist/rich-reference/kinds/entity.d.js

@@ -0,0 +1 @@
+export{};

package/dist/rich-reference/kinds/entity.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Built-in `entity` reference kind.
+ *
+ * Represents a typed entity instance governed by a {@link ContractEntitySpec}
+ * registered in an {@link EntityRegistry}. The `slug` field names the entity
+ * type (looked up via `registry.get(slug, version?)`); `id` identifies the
+ * specific instance. `label` and `url` are optional display aids that may
+ * carry PII — both are declared as `sensitiveFields`. `id` is also sensitive
+ * since it directly identifies an entity instance.
+ */
+import { z } from 'zod';
+import type { ContractEntitySpec } from '../../entities/defineContractEntity.js';
+import type { EntityRegistry } from '../../entities/registry.js';
+declare const EntityPayloadSchema: z.ZodObject<{
+    slug: z.ZodString;
+    id: z.ZodString;
+    version: z.ZodOptional<z.ZodString>;
+    label: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type EntityPayload = z.infer<typeof EntityPayloadSchema>;
+export declare const entityKind: import("..").ReferenceKindDefinition<{
+    slug: string;
+    id: string;
+    version?: string | undefined;
+    label?: string | undefined;
+    url?: string | undefined;
+}>;
+/**
+ * Resolve the {@link ContractEntitySpec} for an entity reference payload.
+ *
+ * Wires `EntityRegistry.get(slug, version?)` into the entity kind's resolution
+ * path so callers can look up the governing spec for any entity reference
+ * without coupling to a global registry singleton.
+ *
+ * Returns `undefined` when no matching spec is registered.
+ *
+ * @param payload  - Validated entity reference payload (from `entityKind.validate`).
+ * @param registry - The `EntityRegistry` instance holding registered entity specs.
+ */
+export declare function resolveEntitySpec(payload: EntityPayload, registry: EntityRegistry): ContractEntitySpec | undefined;
+export declare const entityKindGoalDoc: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "goal";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export declare const entityKindUsageDoc: {
+    id: string;
+    title: string;
+    summary: string;
+    kind: "usage";
+    visibility: "public";
+    route: string;
+    tags: string[];
+    body: string;
+};
+export {};

package/dist/rich-reference/kinds/entity.js

@@ -0,0 +1,27 @@
+import{z as e}from"zod";import{defineReferenceKind as n}from"../define-kind.js";const r=e.object({slug:e.string().min(1),id:e.string().min(1),version:e.string().optional(),label:e.string().optional(),url:e.string().url().optional()});export const entityKind=n({id:"entity",schema:r,sensitiveFields:["id","label","url"],defaultPreview:"inline-card",defaultPanel:"drawer",icon:"box"});export function resolveEntitySpec(t,i){return i.get(t.slug,t.version)}export const entityKindGoalDoc={id:"docs.contracts-spec.rich-reference.kinds.entity.goal",title:"entityKind \u2014 goal",summary:"Canonical reference kind for typed entity instances governed by ContractEntitySpec.",kind:"goal",visibility:"public",route:"/docs/contracts-spec/rich-reference/kinds/entity/goal",tags:["rich-reference","entity","kind","contracts-spec"],body:"# entityKind\n\n`entityKind` is the built-in `ReferenceKindDefinition` for entity references. Each instance\ncarries a `slug` (entity type key) and an `id` (instance identifier). The slug resolves to a\n`ContractEntitySpec` via `resolveEntitySpec(payload, registry)`, connecting RichReference\ngovernance (redaction, policy, audit) to the contracts-spec entity graph."};export const entityKindUsageDoc={id:"docs.contracts-spec.rich-reference.kinds.entity.usage",title:"entityKind \u2014 usage",summary:"How to build entity references and resolve entity specs from payloads.",kind:"usage",visibility:"public",route:"/docs/contracts-spec/rich-reference/kinds/entity/usage",tags:["rich-reference","entity","kind"],body:`# Using entityKind
+
+## Building a reference
+
+\`\`\`ts
+import { asReferenceInstanceId, asReferenceKindId } from '@lssm/lib.contracts-spec/rich-reference';
+import { entityKind } from '@lssm/lib.contracts-spec/rich-reference/kinds/entity';
+
+const ref = {
+  kindId: asReferenceKindId('entity'),
+  id: asReferenceInstanceId('user-42'),
+  payload: { slug: 'user', id: 'user-42', label: 'Ada Lovelace' },
+  redactionState: 'unredacted',
+} satisfies RichReference<EntityPayload>;
+\`\`\`
+
+## Resolving the entity spec
+
+\`\`\`ts
+import { resolveEntitySpec } from '@lssm/lib.contracts-spec/rich-reference/kinds/entity';
+
+const spec = resolveEntitySpec(ref.payload, registry);
+// spec is ContractEntitySpec | undefined
+\`\`\`
+
+\`sensitiveFields\` for \`entityKind\` are \`['id', 'label', 'url']\`. The RichReference runtime
+will redact these fields based on the active KindPolicy.`};

package/dist/rich-reference/kinds/file.d.js

@@ -0,0 +1 @@
+export{};

package/dist/rich-reference/kinds/file.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Built-in `file` reference kind.
+ *
+ * Represents a governed file or asset in a workspace (path + content type).
+ * `path` and `previewExcerpt` are sensitive — paths can encode tenant
+ * structure; excerpts carry verbatim content.
+ */
+import { z } from 'zod';
+declare const FilePayloadSchema: z.ZodObject<{
+    storeKey: z.ZodString;
+    path: z.ZodString;
+    contentType: z.ZodOptional<z.ZodString>;
+    sizeBytes: z.ZodOptional<z.ZodNumber>;
+    previewExcerpt: z.ZodOptional<z.ZodString>;
+    checksum: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FilePayload = z.infer<typeof FilePayloadSchema>;
+export declare const fileKind: import("..").ReferenceKindDefinition<{
+    storeKey: string;
+    path: string;
+    contentType?: string | undefined;
+    sizeBytes?: number | undefined;
+    previewExcerpt?: string | undefined;
+    checksum?: string | undefined;
+}>;
+export {};

package/dist/rich-reference/kinds/file.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{defineReferenceKind as i}from"../define-kind.js";const t=e.object({storeKey:e.string().min(1),path:e.string().min(1),contentType:e.string().optional(),sizeBytes:e.number().int().nonnegative().optional(),previewExcerpt:e.string().optional(),checksum:e.string().optional()});export const fileKind=i({id:"file",schema:t,sensitiveFields:["path","previewExcerpt","checksum"],defaultPreview:"inline-card",defaultPanel:"drawer",icon:"file"});

package/dist/rich-reference/kinds/index.d.js

@@ -0,0 +1 @@
+import{codeSymbolKind}from"./code-symbol.js";import{databaseRecordKind}from"./database-record.js";import{fileKind}from"./file.js";import{linkKind}from"./link.js";import{mediaKind}from"./media.js";import{objectKind}from"./object.js";export{entityKind,entityKindGoalDoc,entityKindUsageDoc,resolveEntitySpec}from"./entity.js";export{codeSymbolKind,databaseRecordKind,fileKind,linkKind,mediaKind,objectKind};

package/dist/rich-reference/kinds/index.d.ts

@@ -0,0 +1,70 @@
+import { codeSymbolKind } from './code-symbol.js';
+import { databaseRecordKind } from './database-record.js';
+import { fileKind } from './file.js';
+import { linkKind } from './link.js';
+import { mediaKind } from './media.js';
+import { objectKind } from './object.js';
+export type { CodeSymbolPayload } from './code-symbol.js';
+export type { DatabaseRecordPayload } from './database-record.js';
+export type { EntityPayload } from './entity.js';
+export { entityKind, entityKindGoalDoc, entityKindUsageDoc, resolveEntitySpec, } from './entity.js';
+export type { FilePayload } from './file.js';
+export type { LinkPayload } from './link.js';
+export type { MediaPayload } from './media.js';
+export type { ObjectPayload } from './object.js';
+export { codeSymbolKind, databaseRecordKind, fileKind, linkKind, mediaKind, objectKind, };
+/** Frozen tuple of every built-in kind for invariant tests + leak scans. */
+export declare const BUILT_IN_REFERENCE_KINDS: readonly [import("..").ReferenceKindDefinition<{
+    databaseKey: string;
+    schemaKey: string;
+    tableName: string;
+    primaryKey: string;
+    naturalKey?: string | undefined;
+    displayValue?: string | undefined;
+    url?: string | undefined;
+}>, import("..").ReferenceKindDefinition<{
+    domain: string;
+    id: string;
+    label?: string | undefined;
+    description?: string | undefined;
+    href?: string | undefined;
+}>, import("..").ReferenceKindDefinition<{
+    url: string;
+    title?: string | undefined;
+    snippet?: string | undefined;
+    domain?: string | undefined;
+    imageUrl?: string | undefined;
+}>, import("..").ReferenceKindDefinition<{
+    storeKey: string;
+    path: string;
+    contentType?: string | undefined;
+    sizeBytes?: number | undefined;
+    previewExcerpt?: string | undefined;
+    checksum?: string | undefined;
+}>, import("..").ReferenceKindDefinition<{
+    mediaType: "audio" | "image" | "video";
+    url: string;
+    posterUrl?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    durationMs?: number | undefined;
+    captions?: string | undefined;
+    altText?: string | undefined;
+}>, import("..").ReferenceKindDefinition<{
+    language: string;
+    symbol: string;
+    kind?: "class" | "constant" | "function" | "interface" | "method" | "other" | "type" | "variable" | undefined;
+    path?: string | undefined;
+    startLine?: number | undefined;
+    endLine?: number | undefined;
+    signature?: string | undefined;
+    snippet?: string | undefined;
+}>, import("..").ReferenceKindDefinition<{
+    slug: string;
+    id: string;
+    version?: string | undefined;
+    label?: string | undefined;
+    url?: string | undefined;
+}>];
+/** Register all seven built-in kinds. Idempotent: dedupes per registry's contract. */
+export declare function registerBuiltInReferenceKinds(): void;

package/dist/rich-reference/kinds/index.js

@@ -0,0 +1 @@
+import{registerKind as o}from"../registry.js";import{codeSymbolKind}from"./code-symbol.js";import{databaseRecordKind}from"./database-record.js";import{entityKind as t}from"./entity.js";import{fileKind}from"./file.js";import{linkKind}from"./link.js";import{mediaKind}from"./media.js";import{objectKind}from"./object.js";export{entityKind,entityKindGoalDoc,entityKindUsageDoc,resolveEntitySpec}from"./entity.js";export{codeSymbolKind,databaseRecordKind,fileKind,linkKind,mediaKind,objectKind};export const BUILT_IN_REFERENCE_KINDS=Object.freeze([databaseRecordKind,objectKind,linkKind,fileKind,mediaKind,codeSymbolKind,t]);export function registerBuiltInReferenceKinds(){for(const e of BUILT_IN_REFERENCE_KINDS)o(e)}

package/dist/rich-reference/kinds/link.d.js

@@ -0,0 +1 @@
+export{};

package/dist/rich-reference/kinds/link.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Built-in `link` reference kind.
+ *
+ * Represents an external or internal URL with optional preview metadata.
+ * `url` itself may encode tenant identifiers; `title` and `snippet` may
+ * carry confidential preview content. All three are sensitive.
+ */
+import { z } from 'zod';
+declare const LinkPayloadSchema: z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    snippet: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodString>;
+    imageUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type LinkPayload = z.infer<typeof LinkPayloadSchema>;
+export declare const linkKind: import("..").ReferenceKindDefinition<{
+    url: string;
+    title?: string | undefined;
+    snippet?: string | undefined;
+    domain?: string | undefined;
+    imageUrl?: string | undefined;
+}>;
+export {};

package/dist/rich-reference/kinds/link.js

@@ -0,0 +1 @@
+import{z as i}from"zod";import{defineReferenceKind as n}from"../define-kind.js";const e=i.object({url:i.string().min(1),title:i.string().optional(),snippet:i.string().optional(),domain:i.string().optional(),imageUrl:i.string().optional()});export const linkKind=n({id:"link",schema:e,sensitiveFields:["url","title","snippet","imageUrl"],defaultPreview:"inline-link",defaultPanel:"popover",icon:"link"});

package/dist/rich-reference/kinds/media.d.js

@@ -0,0 +1 @@
+export{};

package/dist/rich-reference/kinds/media.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Built-in `media` reference kind.
+ *
+ * Represents an image, video, or audio asset with optional preview metadata.
+ * `url`, `posterUrl`, and `captions` may carry tenant data and are
+ * sensitive.
+ */
+import { z } from 'zod';
+declare const MediaPayloadSchema: z.ZodObject<{
+    mediaType: z.ZodEnum<{
+        audio: "audio";
+        image: "image";
+        video: "video";
+    }>;
+    url: z.ZodString;
+    posterUrl: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    captions: z.ZodOptional<z.ZodString>;
+    altText: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MediaPayload = z.infer<typeof MediaPayloadSchema>;
+export declare const mediaKind: import("..").ReferenceKindDefinition<{
+    mediaType: "audio" | "image" | "video";
+    url: string;
+    posterUrl?: string | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    durationMs?: number | undefined;
+    captions?: string | undefined;
+    altText?: string | undefined;
+}>;
+export {};

package/dist/rich-reference/kinds/media.js

@@ -0,0 +1 @@
+import{z as i}from"zod";import{defineReferenceKind as e}from"../define-kind.js";const t=i.object({mediaType:i.enum(["image","video","audio"]),url:i.string().min(1),posterUrl:i.string().optional(),width:i.number().int().positive().optional(),height:i.number().int().positive().optional(),durationMs:i.number().int().nonnegative().optional(),captions:i.string().optional(),altText:i.string().optional()});export const mediaKind=e({id:"media",schema:t,sensitiveFields:["url","posterUrl","captions","altText"],defaultPreview:"inline-card",defaultPanel:"modal",icon:"image"});

package/dist/rich-reference/kinds/object.d.js

@@ -0,0 +1 @@
+export{};

package/dist/rich-reference/kinds/object.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Built-in `object` reference kind.
+ *
+ * Represents a generic domain object identified by `domain` + `id`. Use for
+ * cross-feature references where no more specific kind applies. `metadata`
+ * may carry sensitive labels; declared accordingly.
+ */
+import { z } from 'zod';
+declare const ObjectPayloadSchema: z.ZodObject<{
+    domain: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    href: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ObjectPayload = z.infer<typeof ObjectPayloadSchema>;
+export declare const objectKind: import("..").ReferenceKindDefinition<{
+    domain: string;
+    id: string;
+    label?: string | undefined;
+    description?: string | undefined;
+    href?: string | undefined;
+}>;
+export {};

package/dist/rich-reference/kinds/object.js

@@ -0,0 +1 @@
+import{z as e}from"zod";import{defineReferenceKind as i}from"../define-kind.js";const o=e.object({domain:e.string().min(1),id:e.string().min(1),label:e.string().optional(),description:e.string().optional(),href:e.string().optional()});export const objectKind=i({id:"object",schema:o,sensitiveFields:["label","description"],defaultPreview:"inline-chip",defaultPanel:"popover",icon:"box"});

package/dist/rich-reference/markdown-envelope.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Markdown envelope for RichBlock — agent round-trip surface (plan slice S-9).
+ *
+ * Provides the symmetric copy-as-markdown / from-markdown pipeline used by the
+ * AI-agent surface so that a chat transcript can travel through a markdown
+ * editor, an agent's tool output, or a copy-paste boundary and round-trip
+ * back into a fully-annotated RichBlock without leaking redacted payloads.
+ *
+ * Wire conventions:
+ *   - Reference segment       → `[label](rich-ref:{kindId}/{refId})`
+ *   - Redacted reference      → `[redacted:{kindId}]({denialTokenWireForm})`
+ *
+ * `fromMarkdown()` re-validates every `redacted:` token via the provided
+ * signer. Invalid HMAC ⇒ FAIL CLOSED: the link is dropped and the reference
+ * is replaced with a minimal text marker (`[invalid-redaction]`). The function
+ * NEVER auto-unredacts — a parsed `redacted:` segment becomes a reference
+ * segment whose `denialToken` carries the validated wire form (the runtime
+ * may later show "redacted" UI), not a real payload.
+ *
+ * Re-annotation: the remaining text is forwarded to the kind-aware
+ * `RichContentDetector` so freshly-pasted ref-like patterns become
+ * annotations again on read.
+ */
+import type { DenialTokenSigner } from './denial-token.js';
+import type { Subject } from './ports/subject-provider.js';
+import { type DenialToken, type ReferenceInstanceId, type ReferenceKindId } from './types.js';
+/** Verbosity preference passed to `toMarkdown`. */
+export type MarkdownVerbosity = 'standard' | 'compact';
+export interface MarkdownEnvelopePreferences {
+    readonly verbosity?: MarkdownVerbosity;
+}
+export interface MarkdownBlockReference {
+    readonly kindId: ReferenceKindId;
+    readonly refId: ReferenceInstanceId;
+    readonly label?: string;
+    readonly anchor?: number;
+    /** Non-empty when the ref was previously denied; rendered as wire form. */
+    readonly denialToken?: DenialToken;
+}
+export type MarkdownBlockSegment = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'reference';
+    readonly reference: MarkdownBlockReference;
+};
+export type MarkdownBlockKind = 'code' | 'diff' | 'markdown' | 'table' | 'image' | 'embed' | 'plain';
+/** Minimal block envelope used by the markdown round-trip. */
+export interface MarkdownEnvelopeBlock {
+    readonly kind: MarkdownBlockKind;
+    readonly text: string;
+    readonly segments: ReadonlyArray<MarkdownBlockSegment>;
+}
+/** Build a default copy-as-markdown handler for `<RichBlock>`. */
+export declare function defaultCopyMarkdownHandler(block: MarkdownEnvelopeBlock, prefs?: MarkdownEnvelopePreferences): string;
+/** Serialize a RichBlock to markdown. Stable, deterministic, no escaping hacks. */
+export declare function toMarkdown(block: MarkdownEnvelopeBlock, prefs?: MarkdownEnvelopePreferences): string;
+export interface FromMarkdownContext {
+    readonly subject: Subject;
+    readonly signer: DenialTokenSigner;
+    /** Block kind to attach to the parsed envelope. Defaults to `'markdown'`. */
+    readonly kind?: MarkdownBlockKind;
+}
+/**
+ * Re-parse a markdown blob back into a RichBlock envelope.
+ *
+ * - Recognized `rich-ref:` links become reference segments.
+ * - `redacted:` link targets are validated via `ctx.signer.verify`; invalid
+ *   tokens are dropped (FAIL CLOSED) and replaced with a text marker.
+ * - The detector is invoked on each text region for re-annotation; detected
+ *   ids become additional reference segments adjacent to the surrounding text.
+ */
+export declare function fromMarkdown(md: string, ctx: FromMarkdownContext): Promise<MarkdownEnvelopeBlock>;

package/dist/rich-reference/markdown-envelope.js

@@ -0,0 +1 @@
+import{DENIAL_TOKEN_PREFIX as u,looksLikeDenialToken as g}from"./denial-token-shape.js";import{createRichContentDetector as I}from"./detector.js";import{asReferenceInstanceId as f,asReferenceKindId as p}from"./types.js";const l="rich-ref:";const w=/\[([^\]]*)\]\(([^)]+)\)/g;export function defaultCopyMarkdownHandler(e,n){return toMarkdown(e,n)}export function toMarkdown(e,n){const o=n?.verbosity??"standard",t=[];for(const r of e.segments){if(r.type==="text"){t.push(r.text);continue}t.push(M(r.reference,o))}return t.join("")}function M(e,n){if(e.denialToken)return`[${`redacted:${e.kindId}`}](${e.denialToken})`;const o=e.label??`${e.kindId}:${e.refId}`,t=`${l}${e.kindId}/${e.refId}`;if(n==="compact")return`[${o}](${t})`;return`[${o}](${t})`}export async function fromMarkdown(e,n){const o=[],t=I();let r=0;for(const d of e.matchAll(w)){const i=d.index??0;if(i>r){const k=e.slice(r,i);y(k,o,t)}const[,c="",a=""]=d,s=m(c,a,n.signer);if(s)o.push({type:"reference",reference:s});else o.push({type:"text",text:"[invalid-redaction]"});r=i+d[0].length}if(r<e.length)y(e.slice(r),o,t);n.subject;return{kind:n.kind??"markdown",text:e,segments:o}}function y(e,n,o){if(e.length===0)return;const t=o.detect(e);if(t.annotations.length===0){n.push({type:"text",text:e});return}n.push({type:"text",text:e});for(const r of t.annotations)n.push({type:"reference",reference:{kindId:r.kindId,refId:r.id}})}function m(e,n,o){if(g(n)){const c=o.verify(n);if(!c)return;const a=c.slice(u.length),s=a.lastIndexOf(":");return{kindId:p(a.slice(0,s)),refId:f(""),denialToken:c,label:e}}if(!n.startsWith(l))return;const t=n.slice(l.length),r=t.indexOf("/");if(r<=0||r>=t.length-1)return;const d=p(t.slice(0,r)),i=f(t.slice(r+1));return{kindId:d,refId:i,label:e||void 0}}

package/dist/rich-reference/ports/audit-sink.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `AuditSink` port — receives one record per policy/redaction decision.
+ *
+ * Implemented by `surface-runtime` (default `ConsoleAuditSink`, S-3) and by
+ * production sinks registered through the app composition root.
+ *
+ * `AuditRecord` deliberately EXCLUDES payload values (R-8 mitigation). Only
+ * field names (e.g. `redactionsApplied: ["email","phone"]`) are recorded.
+ */
+import type { ReferenceInstanceId, ReferenceKindId } from '../types.js';
+import type { Subject } from './subject-provider.js';
+/** Stable shape of one audit decision. */
+export interface AuditRecord {
+    readonly timestamp: string;
+    readonly adapter: 'rest' | 'graphql' | 'mcp' | 'unknown';
+    readonly kindId: ReferenceKindId;
+    readonly refId?: ReferenceInstanceId;
+    readonly subject?: Pick<Subject, 'id' | 'kind' | 'tenantId'>;
+    readonly delegationChain?: ReadonlyArray<string>;
+    readonly decision: 'permit' | 'partial' | 'deny' | 'hidden';
+    readonly redactionsApplied: ReadonlyArray<string>;
+    readonly traceId?: string;
+}
+/**
+ * Sink receiving one `AuditRecord` per decision. Development and optional
+ * telemetry consumers may use a non-blocking sink with structured drop
+ * warnings. Required governance consumers MUST await a durable implementation
+ * and fail closed when persistence rejects; see `DurableAuditSink`.
+ */
+export interface AuditSink {
+    readonly record: (entry: AuditRecord) => Promise<void> | void;
+}

package/dist/rich-reference/ports/coarse-preferences-provider.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `CoarsePreferencesProvider` port — resolves server-side personalization
+ * defaults for a subject.
+ *
+ * Implemented by `personalization` (S-4). The "coarse" layer is what crosses
+ * the wire; the "fine" layer (client-only, session-state) is handled by the
+ * client hook in personalization and never appears in agent payloads (AC-14).
+ */
+import type { Subject } from './subject-provider.js';
+/** Inline trigger style preference. */
+export type CoarseTrigger = 'hover' | 'tap' | 'long-press' | 'focus' | 'explicit';
+/** Default panel mode preference. */
+export type CoarsePanelMode = 'drawer' | 'popover' | 'modal' | 'route';
+/** Density of detail in default presentations. */
+export type CoarseDensity = 'compact' | 'comfortable' | 'spacious';
+/** Verbosity of agent-facing renders. */
+export type CoarseVerbosity = 'terse' | 'normal' | 'verbose';
+/**
+ * Resolved coarse preferences. `enrichedKinds` defaults to all registered
+ * kinds when undefined; `perKindOptOut` is intersected with the registered
+ * set at runtime so a stale opt-out entry cannot mask new kinds.
+ */
+export interface CoarsePreferences {
+    readonly enrichedKinds?: ReadonlyArray<string>;
+    readonly perKindOptOut?: ReadonlyArray<string>;
+    readonly trigger?: CoarseTrigger;
+    readonly panelMode?: CoarsePanelMode;
+    readonly density?: CoarseDensity;
+    readonly verbosity?: CoarseVerbosity;
+    readonly expansion?: 'collapsed' | 'expanded';
+}
+/**
+ * Resolve coarse preferences for one subject. The implementation is
+ * responsible for tenant-scoped caching using `(tenantId, subjectId, …)` as
+ * the key (F-7 mitigation).
+ */
+export interface CoarsePreferencesProvider {
+    readonly resolveCoarsePreferences: (subject: Subject) => Promise<CoarsePreferences> | CoarsePreferences;
+}

package/dist/rich-reference/ports/durable-audit-sink.d.ts

@@ -0,0 +1,46 @@
+import type { AuditRecord, AuditSink } from './audit-sink.js';
+export type AuditDeliveryStatus = 'pending' | 'leased' | 'delivered' | 'dead_letter';
+export interface AuditDeliveryClaim {
+    readonly destination: string;
+    readonly workerId: string;
+    readonly availableThrough: string;
+    readonly leaseExpiresAt: string;
+    readonly limit: number;
+}
+export interface ClaimedAuditDelivery {
+    readonly recordDigest: `sha256:${string}`;
+    readonly record: AuditRecord;
+    readonly attempts: number;
+}
+export interface AuditDeliveryLease {
+    readonly recordDigest: `sha256:${string}`;
+    readonly destination: string;
+    readonly workerId: string;
+}
+export interface AuditDeliveryFailure extends AuditDeliveryLease {
+    readonly availableAt: string;
+    readonly errorCode: string;
+    readonly maxAttempts: number;
+}
+export interface AuditDeliveryHealth {
+    readonly pending: number;
+    readonly leased: number;
+    readonly delivered: number;
+    readonly deadLetter: number;
+    readonly healthy: boolean;
+}
+/**
+ * Durable audit implementations persist the payload-free decision before the
+ * governed result proceeds, then expose bounded delivery and recovery.
+ */
+export interface DurableAuditSink extends AuditSink {
+    readonly claim: (input: AuditDeliveryClaim) => Promise<readonly ClaimedAuditDelivery[]>;
+    readonly acknowledge: (input: AuditDeliveryLease) => Promise<boolean>;
+    readonly fail: (input: AuditDeliveryFailure) => Promise<'retry_scheduled' | 'dead_lettered' | 'stale_lease'>;
+    readonly recover: (input: {
+        readonly recordDigest: `sha256:${string}`;
+        readonly destination: string;
+        readonly availableAt: string;
+    }) => Promise<boolean>;
+    readonly health: (destination: string) => Promise<AuditDeliveryHealth>;
+}