@lssm/lib.contracts-spec 17.3.2

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

@@ -0,0 +1,12 @@
+/**
+ * Public port barrel for the RichReference governance surface.
+ *
+ * No `registerDocBlocks` calls and no runtime side-effects: this barrel only
+ * re-exports types and interfaces consumed by composition roots (S-2) and
+ * implementations (S-3, S-4).
+ */
+export type { AuditRecord, AuditSink } from './audit-sink.js';
+export type { CoarseDensity, CoarsePanelMode, CoarsePreferences, CoarsePreferencesProvider, CoarseTrigger, CoarseVerbosity, } from './coarse-preferences-provider.js';
+export type { AuditDeliveryClaim, AuditDeliveryFailure, AuditDeliveryHealth, AuditDeliveryLease, AuditDeliveryStatus, ClaimedAuditDelivery, DurableAuditSink, } from './durable-audit-sink.js';
+export type { KindPolicy, KindPolicyProvider, } from './kind-policy-provider.js';
+export type { Subject, SubjectKind, SubjectProvider, SubjectRequestContext, } from './subject-provider.js';

package/dist/rich-reference/ports/kind-policy-provider.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `KindPolicyProvider` port — resolves the kind-level policy for a
+ * (kindId, subject) pair.
+ *
+ * Implemented by `surface-runtime` (S-3) via its RoleMorph adapter. The
+ * shape `KindPolicy` is the canonical wire-out from layer 1 of the
+ * two-layer governance model: instance-level checks happen inside each
+ * kind's handler (S-3).
+ */
+import type { ReferenceKindId, RichReferenceAction } from '../types.js';
+import type { Subject } from './subject-provider.js';
+/**
+ * Kind-level policy decision returned for one (kindId, subject) pair.
+ *
+ * - `visible` gates rendering wholesale.
+ * - `redactedFields` is the policy intersection — payload field names that
+ *   MUST be redacted before crossing any adapter. Must be a subset of the
+ *   kind's declared `sensitiveFields`; the runtime enforces this invariant.
+ * - `allowedActions` is the post-policy boundary set. Empty array means no
+ *   actions are permitted for this subject on this kind.
+ */
+export interface KindPolicy {
+    readonly visible: boolean;
+    readonly redactedFields: ReadonlyArray<string>;
+    readonly allowedActions: ReadonlyArray<RichReferenceAction>;
+    readonly explanation?: string;
+}
+/**
+ * Resolve a kind-level policy. Implementations MUST fail closed (return
+ * `{ visible: false, redactedFields: [], allowedActions: [] }`) on missing
+ * subject (AC-12) and SHOULD log to the audit sink on every decision.
+ */
+export interface KindPolicyProvider {
+    readonly getKindPolicy: (kindId: ReferenceKindId, subject: Subject | undefined) => Promise<KindPolicy> | KindPolicy;
+}

package/dist/rich-reference/ports/subject-provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `SubjectProvider` port — resolves the authenticated subject for a request.
+ *
+ * Implemented by `authos-runtime` (S-3). The port is owned by contracts-spec
+ * to keep the policy surface declared in the lowest layer; no contracts-spec
+ * code imports from authos-runtime.
+ */
+/** Identity classification for the resolved subject. */
+export type SubjectKind = 'user' | 'agent' | 'service' | 'anonymous';
+/**
+ * Subject resolved for a single resolve request. `id` is opaque to the
+ * runtime; `tenantId` MUST be set whenever the subject is tenant-scoped, since
+ * it is part of the personalization cache key (F-7 mitigation).
+ */
+export interface Subject {
+    readonly id: string;
+    readonly kind: SubjectKind;
+    readonly tenantId?: string;
+    /** Role tags, used by RoleMorph adapters (S-3). */
+    readonly roles?: ReadonlyArray<string>;
+    /** Delegation chain, audited but never logged in payload form (R-8). */
+    readonly delegationChain?: ReadonlyArray<string>;
+}
+/**
+ * Opaque request context handed to the provider. The runtime guarantees a
+ * fresh context per resolve invocation so providers cannot leak state
+ * across requests.
+ */
+export interface SubjectRequestContext {
+    readonly headers?: Readonly<Record<string, string | undefined>>;
+    readonly traceId?: string;
+    readonly sessionId?: string;
+}
+/**
+ * Resolve a subject for one request. MUST return `undefined` (and the runtime
+ * MUST fail closed, per AC-12) when no authenticated subject is available.
+ */
+export interface SubjectProvider {
+    readonly getSubjectForRequest: (ctx: SubjectRequestContext) => Promise<Subject | undefined> | Subject | undefined;
+}

package/dist/rich-reference/redaction.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `applyKindRedaction` — walks a kind's `sensitiveFields` and replaces
+ * matching payload values with HMAC-signed `DenialToken` wire strings.
+ *
+ * Read-time redaction (not at detector/persist time) so schema-evolution
+ * events (new sensitive field) are honored on the next read without
+ * re-running the detector (F-8 mitigation).
+ *
+ * Returned reference always has its `redactionState` recomputed from the
+ * decision; the runtime-enforcer (S-2) double-checks this invariant before
+ * propagation to any adapter.
+ */
+import type { ReferenceKindDefinition } from './define-kind.js';
+import type { DenialTokenSigner } from './denial-token.js';
+import type { RichReference } from './types.js';
+/** Policy decision for a single (kindId, subject, instance) tuple. */
+export interface KindRedactionDecision {
+    readonly visible: boolean;
+    readonly redactedFields: ReadonlyArray<string>;
+    readonly explanation?: string;
+}
+/** Apply a kind-level redaction decision to one `RichReference`. */
+export declare function applyKindRedaction<TPayload extends Record<string, unknown>>(kind: ReferenceKindDefinition<TPayload>, instance: RichReference<TPayload>, decision: KindRedactionDecision, signer: DenialTokenSigner): RichReference<TPayload>;

package/dist/rich-reference/redaction.js

@@ -0,0 +1 @@
+export function applyKindRedaction(t,e,a,r){if(!a.visible)return{...e,payload:l(e.payload),redactionState:"hidden"};const i=new Set(t.sensitiveFields),n=new Set(a.redactedFields);for(const o of n)if(!i.has(o))n.delete(o);if(n.size===0)return{...e,redactionState:"unredacted"};const d={...e.payload};for(const o of n)d[o]=r.mint(t.id);const c=n.size===i.size&&i.size>0?"fully-redacted":"partially-redacted";return{...e,payload:d,redactionState:c}}function l(t){const e={};for(const a of Object.keys(t))e[a]=void 0;return e}

package/dist/rich-reference/registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Process-global `ReferenceKindRegistry`.
+ *
+ * Zero side-effects on import: kinds are registered via explicit `registerKind`
+ * calls (composition root or kind module entrypoint). `getKind` throws on
+ * unknown ids so handlers cannot silently route around governance; `listKinds`
+ * powers payload-leak generated tests (S-3) and runtime invariants (S-2).
+ */
+import type { ReferenceKindDefinition } from './define-kind.js';
+import type { ReferenceKindId } from './types.js';
+/**
+ * Anonymous kind definition (payload erased). Used by the registry's external
+ * surface so callers don't have to thread their payload generic through every
+ * `registerKind` call. Type-narrow versions are recoverable via `getKind`.
+ */
+export type AnyReferenceKindDefinition = ReferenceKindDefinition<Record<string, unknown>>;
+/**
+ * Register a kind. Throws on duplicate id (silent overrides hide bugs).
+ *
+ * Generic-on-payload so TS infers `TPayload` from the concrete kind at the
+ * call site, sidestepping variance issues that block assigning
+ * `ReferenceKindDefinition<{ a: string }>` to the erased
+ * `ReferenceKindDefinition<Record<string, unknown>>` parameter.
+ */
+export declare function registerKind<TPayload extends Record<string, unknown>>(definition: ReferenceKindDefinition<TPayload>): void;
+/** Fetch a registered kind by id; throws on unknown id. */
+export declare function getKind<TPayload extends Record<string, unknown>>(id: ReferenceKindId): ReferenceKindDefinition<TPayload>;
+/** Optional fetch — returns undefined for unknown ids (e.g. for detectors). */
+export declare function tryGetKind<TPayload extends Record<string, unknown>>(id: ReferenceKindId): ReferenceKindDefinition<TPayload> | undefined;
+/** Enumerate every registered kind (for runtime invariants + leak tests). */
+export declare function listKinds(): ReadonlyArray<ReferenceKindDefinition<never>>;
+/** Test-only: clear the registry. Production code must not call this. */
+export declare function unregisterKind(id: ReferenceKindId): void;
+/** Test-only: clear ALL kinds. Production code must not call this. */
+export declare function clearReferenceKindRegistry(): void;

package/dist/rich-reference/registry.js

@@ -0,0 +1 @@
+const n=new Map;export function registerKind(e){if(n.has(e.id))throw Error(`ReferenceKindRegistry: kind "${e.id}" is already registered. Use unregisterKind first if intentional.`);n.set(e.id,e)}export function getKind(e){const i=n.get(e);if(!i)throw Error(`ReferenceKindRegistry: kind "${e}" is not registered. Did you forget to call registerKind() in the composition root?`);return i}export function tryGetKind(e){return n.get(e)}export function listKinds(){return Array.from(n.values())}export function unregisterKind(e){n.delete(e)}export function clearReferenceKindRegistry(){n.clear()}

package/dist/rich-reference/runtime/dev-invariants.d.ts

@@ -0,0 +1,18 @@
+import type { Subject } from '../ports/subject-provider.js';
+import type { ReferenceInstanceId, ReferenceKindId, RichReference } from '../types.js';
+export interface RichReferenceTelemetryEvent {
+    readonly event: 'rich-reference.resolved';
+    readonly kindId: ReferenceKindId;
+    readonly refId: ReferenceInstanceId;
+    readonly tenantId?: string;
+    readonly subjectId?: string;
+    readonly redactionState: RichReference['redactionState'];
+    readonly fieldsRedacted: number;
+    readonly traceId?: string;
+}
+export type RichReferenceTelemetrySink = (event: RichReferenceTelemetryEvent) => void;
+/** Replace the active telemetry sink. Pass `undefined` to disable emission. */
+export declare function enableRichReferenceTelemetry(next: RichReferenceTelemetrySink | undefined): void;
+/** Dev-only assertion: throws if a declared sensitive field survived intact. */
+export declare function assertRedactionApplied(kindId: ReferenceKindId, declaredSensitiveFields: ReadonlyArray<string>, redactedFields: ReadonlyArray<string>, payload: Record<string, unknown>): void;
+export declare function emitResolveTelemetry(reference: RichReference<Record<string, unknown>>, subject: Subject | undefined, redactedFields: ReadonlyArray<string>, traceId?: string): void;

package/dist/rich-reference/runtime/dev-invariants.js

@@ -0,0 +1 @@
+import{looksLikeDenialToken as c}from"../denial-token-shape.js";let o;export function enableRichReferenceTelemetry(e){o=e}export function assertRedactionApplied(e,n,t,i){for(const d of t){if(!n.includes(d))continue;const r=i[d];if(r===void 0||r===null)continue;if(!c(r))throw Error(`[dev] assertRedactionApplied: field "${d}" on kind "${e}" should be a DenialToken but is "${typeof r}".`)}}export function emitResolveTelemetry(e,n,t,i){if(!o)return;o({event:"rich-reference.resolved",kindId:e.kindId,refId:e.id,tenantId:n?.tenantId,subjectId:n?.id,redactionState:e.redactionState,fieldsRedacted:t.length,traceId:i})}

package/dist/rich-reference/runtime/dispatch.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `ReferenceRuntime` dispatch — coordinates handler invocation, kind-policy
+ * lookup, redaction enforcement, and audit emission for resolveBatch /
+ * detail calls.
+ *
+ * Pure orchestration: the runtime itself owns handler registration
+ * (`./runtime.ts`); the redaction wrap lives in `./redaction-enforcer.ts`;
+ * dev-only telemetry/invariants live in `./dev-invariants.ts`.
+ */
+import type { DenialTokenSigner } from '../denial-token.js';
+import type { AuditSink } from '../ports/audit-sink.js';
+import type { KindPolicyProvider } from '../ports/kind-policy-provider.js';
+import type { Subject } from '../ports/subject-provider.js';
+import type { ReferenceInstanceId, ReferenceKindId, RichReference } from '../types.js';
+import type { ReferenceRuntime } from './runtime.js';
+export type AdapterId = 'rest' | 'graphql' | 'mcp' | 'unknown';
+export interface ResolveRequest {
+    readonly kindId: ReferenceKindId;
+    readonly id: ReferenceInstanceId;
+}
+export interface ResolveBatchInput {
+    readonly refs: ReadonlyArray<ResolveRequest>;
+    readonly subject: Subject | undefined;
+    readonly adapter?: AdapterId;
+    readonly traceId?: string;
+    readonly sessionId?: string;
+}
+export interface ResolvedEntry {
+    readonly request: ResolveRequest;
+    readonly outcome: 'found' | 'not-found' | 'forbidden';
+    readonly reference?: RichReference<Record<string, unknown>>;
+    readonly explanation?: string;
+}
+export interface DispatchDependencies {
+    readonly runtime: ReferenceRuntime;
+    readonly policyProvider: KindPolicyProvider;
+    readonly auditSink: AuditSink;
+    readonly signer: DenialTokenSigner;
+}
+export interface ReferenceDispatcher {
+    readonly resolveBatch: (input: ResolveBatchInput) => Promise<ReadonlyArray<ResolvedEntry>>;
+    readonly detail: (request: ResolveRequest, subject: Subject | undefined, ctx?: {
+        adapter?: AdapterId;
+        traceId?: string;
+        sessionId?: string;
+    }) => Promise<ResolvedEntry>;
+}
+export declare function createDispatcher(deps: DispatchDependencies): ReferenceDispatcher;

package/dist/rich-reference/runtime/dispatch.js

@@ -0,0 +1 @@
+import{getKind as g}from"../registry.js";import{assertRedactionApplied as k,emitResolveTelemetry as h}from"./dev-invariants.js";import{enforceRedaction as S}from"./redaction-enforcer.js";export function createDispatcher(r){const f=async(e,i,n,o,t,d)=>{if(o.outcome==="not-found"){u(r.auditSink,e,i,n,"deny",[],t,d);return{request:e,outcome:"not-found"}}if(o.outcome==="forbidden"){u(r.auditSink,e,i,n,"deny",[],t,d);return{request:e,outcome:"forbidden",explanation:o.explanation}}const c=g(e.kindId),a=S(c,o.reference,n,r.signer);k(c.id,c.sensitiveFields,n.redactedFields,a.payload);h(a,i,n.redactedFields,d);u(r.auditSink,e,i,n,P(a.redactionState),n.redactedFields,t,d);return{request:e,outcome:"found",reference:a}};return{resolveBatch:async(e)=>{const i=e.adapter??"unknown",n=new Map;for(const t of e.refs){const d=n.get(t.kindId)??[];d.push(t);n.set(t.kindId,d)}const o=[];for(const[t,d]of n){const c=await r.policyProvider.getKindPolicy(t,e.subject),a=r.runtime.getHandler(t),p={subject:e.subject,traceId:e.traceId,sessionId:e.sessionId},R=d.map((s)=>s.id),m=a.resolveBatch?await a.resolveBatch(R,p):await Promise.all(d.map((s)=>a.resolve(s.id,p)));for(let s=0;s<d.length;s+=1){const I=d[s],v=m[s];o.push(await f(I,e.subject,c,v,i,e.traceId))}}return o},detail:async(e,i,n)=>{const o=await r.policyProvider.getKindPolicy(e.kindId,i),t=r.runtime.getHandler(e.kindId),c=await(t.detail??t.resolve)(e.id,{subject:i,traceId:n?.traceId,sessionId:n?.sessionId});return f(e,i,o,c,n?.adapter??"unknown",n?.traceId)}}}function P(r){if(r==="unredacted")return"permit";if(r==="partially-redacted")return"partial";if(r==="hidden")return"hidden";return"partial"}function u(r,f,l,y,e,i,n,o){r.record({timestamp:new Date().toISOString(),adapter:n,kindId:f.kindId,refId:f.id,subject:l?{id:l.id,kind:l.kind,tenantId:l.tenantId}:void 0,delegationChain:l?.delegationChain,decision:e,redactionsApplied:i,traceId:o})}

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

@@ -0,0 +1,16 @@
+/**
+ * Public barrel for the `ReferenceRuntime` surface.
+ *
+ * No side-effects on import. Pre-split per S-2 size discipline:
+ *  - `./runtime.ts` — handler registration.
+ *  - `./dispatch.ts` — resolveBatch + detail orchestration.
+ *  - `./redaction-enforcer.ts` — post-handler redaction wrap (F-1).
+ *  - `./dev-invariants.ts` — dev-only assertions + telemetry emit.
+ */
+export type { RichReferenceTelemetryEvent, RichReferenceTelemetrySink, } from './dev-invariants.js';
+export { assertRedactionApplied, emitResolveTelemetry, enableRichReferenceTelemetry, } from './dev-invariants.js';
+export type { AdapterId, DispatchDependencies, ReferenceDispatcher, ResolveBatchInput, ResolvedEntry, ResolveRequest, } from './dispatch.js';
+export { createDispatcher } from './dispatch.js';
+export { enforceRedaction } from './redaction-enforcer.js';
+export type { ReferenceRuntime } from './runtime.js';
+export { createReferenceRuntime } from './runtime.js';

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

@@ -0,0 +1 @@
+export{assertRedactionApplied,emitResolveTelemetry,enableRichReferenceTelemetry}from"./dev-invariants.js";export{createDispatcher}from"./dispatch.js";export{enforceRedaction}from"./redaction-enforcer.js";export{createReferenceRuntime}from"./runtime.js";

package/dist/rich-reference/runtime/redaction-enforcer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Post-handler redaction enforcer.
+ *
+ * Every handler return value flows through `enforceRedaction()` BEFORE the
+ * runtime hands the reference to any adapter. Two invariants are enforced:
+ *
+ *  1. Unknown payload fields (anything not part of the kind's schema shape)
+ *     are stripped — a handler cannot smuggle extra data past governance.
+ *  2. The `KindPolicy.redactedFields` set is applied via
+ *     `applyKindRedaction(…)`, replacing matching values with HMAC-signed
+ *     `DenialToken` strings. If the resulting reference still contains
+ *     un-redacted sensitive values, the enforcer throws.
+ *
+ * F-1 + F-6 prevention. The enforcer fails closed: thrown errors abort the
+ * resolve call before any payload reaches the wire.
+ */
+import type { ReferenceKindDefinition } from '../define-kind.js';
+import type { DenialTokenSigner } from '../denial-token.js';
+import type { KindPolicy } from '../ports/kind-policy-provider.js';
+import type { RichReference } from '../types.js';
+export declare function enforceRedaction<TPayload extends Record<string, unknown>>(kind: ReferenceKindDefinition<TPayload>, instance: RichReference<TPayload>, policy: KindPolicy, signer: DenialTokenSigner): RichReference<TPayload>;

package/dist/rich-reference/runtime/redaction-enforcer.js

@@ -0,0 +1 @@
+import{looksLikeDenialToken as f}from"../denial-token-shape.js";import{applyKindRedaction as l}from"../redaction.js";export function enforceRedaction(e,n,i,r){if(!i.visible)return l(e,n,{visible:!1,redactedFields:[]},r);const d=e.validate(n.payload),s=d.success?d.data:n.payload,t=l(e,{...n,payload:s},{visible:!0,redactedFields:i.redactedFields,explanation:i.explanation},r),c=new Set(e.sensitiveFields);for(const o of i.redactedFields){if(!c.has(o))continue;const a=t.payload[o];if(a===void 0||a===null)continue;if(!f(a))throw Error(`ReferenceRuntime.enforceRedaction: handler returned an un-redacted value for sensitive field "${o}" on kind "${e.id}".`)}return t}

package/dist/rich-reference/runtime/runtime.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `ReferenceRuntime` — per-process handler registry for rich references.
+ *
+ * Pure registration surface. Dispatch lives in `./dispatch.ts`; redaction
+ * enforcement lives in `./redaction-enforcer.ts`. Splitting these keeps each
+ * file under the size cap defined in `code-splitting.md` and makes the
+ * post-handler redaction wrap inspectable in isolation.
+ */
+import type { ReferenceHandler } from '../handler.js';
+import type { ReferenceKindId } from '../types.js';
+type AnyReferenceHandler = ReferenceHandler<Record<string, unknown>>;
+/** Per-process registry of handlers keyed by `ReferenceKindId`. */
+export interface ReferenceRuntime {
+    readonly registerHandler: <TPayload extends Record<string, unknown>>(handler: ReferenceHandler<TPayload>) => void;
+    readonly getHandler: (kindId: ReferenceKindId) => AnyReferenceHandler;
+    readonly tryGetHandler: (kindId: ReferenceKindId) => AnyReferenceHandler | undefined;
+    readonly listHandlers: () => ReadonlyArray<AnyReferenceHandler>;
+    readonly hasHandler: (kindId: ReferenceKindId) => boolean;
+    readonly clear: () => void;
+}
+/**
+ * Build a fresh `ReferenceRuntime` instance. Apps register one runtime per
+ * composition root (REST/GraphQL/MCP wirings share a single instance via the
+ * integrations/runtime composition root — see S-2 wire-*.ts).
+ */
+export declare function createReferenceRuntime(): ReferenceRuntime;
+export {};

package/dist/rich-reference/runtime/runtime.js

@@ -0,0 +1 @@
+export function createReferenceRuntime(){const n=new Map;return{registerHandler:(e)=>{const r=e.kind.id;if(n.has(r))throw Error(`ReferenceRuntime: handler for kind "${r}" is already registered. Call clear() or build a fresh runtime for tests.`);n.set(r,e)},getHandler:(e)=>{const r=n.get(e);if(!r)throw Error(`ReferenceRuntime: no handler registered for kind "${e}".`);return r},tryGetHandler:(e)=>n.get(e),listHandlers:()=>Array.from(n.values()),hasHandler:(e)=>n.has(e),clear:()=>{n.clear()}}}

package/dist/rich-reference/types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Canonical RichReference types.
+ *
+ * `RichReference<TPayload>` is the single transport shape for any rich,
+ * subject-scoped, governance-aware reference rendered across REST, GraphQL,
+ * MCP, and agent surfaces.
+ *
+ * `DenialToken` is a TypeScript-branded STRING (not a Symbol — Symbols do not
+ * survive JSON serialization and the token must traverse all three adapters).
+ * Wire form is HMAC-signed; see `./denial-token.ts` for the signer.
+ */
+import type { z } from 'zod';
+/** Branded identifier for a registered reference kind. */
+export type ReferenceKindId = string & {
+    readonly __referenceKindId: unique symbol;
+};
+/** Branded identifier for a single reference instance. */
+export type ReferenceInstanceId = string & {
+    readonly __referenceInstanceId: unique symbol;
+};
+/**
+ * Branded-string denial token. Constructable only via `denial-token.ts`'s
+ * `createDenialTokenSigner(...).mint(...)`. User content cannot produce a
+ * same-typed value at the type level.
+ */
+export type DenialToken = string & {
+    readonly __denialToken: unique symbol;
+};
+/** Sensitivity classification for a reference (per-instance override). */
+export type RichReferenceSensitivity = 'public' | 'internal' | 'confidential' | 'secret';
+/** Redaction state for a reference after policy resolution. */
+export type RichReferenceRedactionState = 'unredacted' | 'partially-redacted' | 'fully-redacted' | 'hidden';
+/** Allowed display variant for the inline trigger. */
+export type ReferencePreviewMode = 'inline-card' | 'inline-chip' | 'inline-link' | 'inline-icon';
+/** Allowed panel mode for the expanded preview surface. */
+export type ReferencePanelMode = 'drawer' | 'popover' | 'modal' | 'route' | 'inline-expand';
+/** Per-action boundary on a reference. */
+export type RichReferenceActionBoundary = 'allowed' | 'allowed_with_conditions' | 'requires_approval' | 'blocked' | 'hidden';
+/** A single action available on a reference, governed by policy. */
+export interface RichReferenceAction {
+    readonly id: string;
+    readonly label: string;
+    readonly boundary: RichReferenceActionBoundary;
+    readonly explanation?: string;
+}
+export type RichReferenceActions = ReadonlyArray<RichReferenceAction>;
+/**
+ * Canonical reference shape. `TPayload` is the kind-specific payload schema's
+ * inferred type; redacted fields are replaced with `DenialToken` values.
+ */
+export interface RichReference<TPayload extends Record<string, unknown> = Record<string, unknown>> {
+    readonly kindId: ReferenceKindId;
+    readonly id: ReferenceInstanceId;
+    readonly payload: TPayload;
+    readonly redactionState: RichReferenceRedactionState;
+    readonly sensitivity?: RichReferenceSensitivity;
+    readonly actions?: RichReferenceActions;
+    readonly label?: string;
+    readonly href?: string;
+}
+/** Zod-typed payload shape for a kind definition. */
+export type ReferencePayloadSchema<TPayload extends Record<string, unknown>> = z.ZodType<TPayload>;
+/** Branded kind-id factory (runtime no-op cast; type-safety only). */
+export declare const asReferenceKindId: (value: string) => ReferenceKindId;
+/** Branded instance-id factory (runtime no-op cast; type-safety only). */
+export declare const asReferenceInstanceId: (value: string) => ReferenceInstanceId;

package/dist/rich-reference/types.js

@@ -0,0 +1 @@
+export const asReferenceKindId=(e)=>e;export const asReferenceInstanceId=(e)=>e;

package/dist/runtime-adapters.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Canonical runtime adapter identities shared by agent and workflow contracts.
+ *
+ * This closed union is a compatibility surface. Adding an adapter requires a
+ * documented migration because exhaustive consumers must handle the new key.
+ */
+export declare const AGENT_RUNTIME_ADAPTER_KEYS: readonly ['langgraph', 'langchain', 'workflow-devkit', 'eve'];
+export type AgentRuntimeAdapterKey = (typeof AGENT_RUNTIME_ADAPTER_KEYS)[number];
+/** Backwards-compatible workflow name for the canonical adapter identity. */
+export type WorkflowRuntimeAdapterKey = AgentRuntimeAdapterKey;
+export declare const AGENT_RUNTIME_CAPABILITY_KEYS: readonly ['sessions', 'checkpoints', 'suspend-resume', 'sandbox', 'connections', 'channels', 'schedules', 'subagent-dispatch', 'eval-hooks', 'approval', 'effect-replay'];
+export type AgentRuntimeCapabilityKey = (typeof AGENT_RUNTIME_CAPABILITY_KEYS)[number];
+export type AgentRuntimeCapabilityStatus = 'supported' | 'unsupported' | 'lossy' | 'not_applicable';
+/**
+ * Serializable capability result used by adapters and conformance reports.
+ * Unsupported or lossy mappings always carry an explicit reason.
+ */
+export interface AgentRuntimeCapabilityDiagnostic {
+    adapter: AgentRuntimeAdapterKey;
+    capability: AgentRuntimeCapabilityKey;
+    status: AgentRuntimeCapabilityStatus;
+    reasonCode?: string;
+    detail?: string;
+    evidenceRefs?: readonly string[];
+}

package/dist/runtime-adapters.js

@@ -0,0 +1 @@
+export const AGENT_RUNTIME_ADAPTER_KEYS=["langgraph","langchain","workflow-devkit","eve"];export const AGENT_RUNTIME_CAPABILITY_KEYS=["sessions","checkpoints","suspend-resume","sandbox","connections","channels","schedules","subagent-dispatch","eval-hooks","approval","effect-replay"];

package/dist/schema-to-markdown.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Schema-to-Markdown Utilities
+ *
+ * Generate markdown from SchemaModel definitions and data.
+ * Provides automatic table, list, and detail view generation
+ * based on schema field introspection.
+ */
+import type { AnySchemaModel } from '@lssm/lib.schema/SchemaModel';
+/**
+ * Options for schema-to-markdown generation
+ */
+export interface SchemaMarkdownOptions {
+    /** Title for the markdown section */
+    title?: string;
+    /** Description to include below the title */
+    description?: string;
+    /** Output format: table for lists, list for simple items, detail for single objects */
+    format?: 'table' | 'list' | 'detail' | 'auto';
+    /** Maximum number of items to render (for arrays) */
+    maxItems?: number;
+    /** Only include these fields (if not specified, all fields are included) */
+    includeFields?: string[];
+    /** Exclude these fields from output */
+    excludeFields?: string[];
+    /** Custom field labels (field name -> display label) */
+    fieldLabels?: Record<string, string>;
+    /** Fields to use for summary in list format */
+    summaryFields?: string[];
+    /** Nesting depth for nested schemas (default: 2) */
+    maxDepth?: number;
+}
+/**
+ * Generate markdown from a SchemaModel and data.
+ * Automatically detects array vs object data and formats accordingly.
+ */
+export declare function schemaToMarkdown(schema: AnySchemaModel, data: unknown, options?: SchemaMarkdownOptions): string;
+/**
+ * Generate a markdown table from array data using schema fields as columns.
+ */
+export declare function schemaToMarkdownTable(schema: AnySchemaModel, items: unknown[], options?: SchemaMarkdownOptions): string;
+/**
+ * Generate a markdown list from array data.
+ * Uses summaryFields to create concise list items.
+ */
+export declare function schemaToMarkdownList(schema: AnySchemaModel, items: unknown[], options?: SchemaMarkdownOptions): string;
+/**
+ * Generate a markdown detail view (key-value pairs) from object data.
+ */
+export declare function schemaToMarkdownDetail(schema: AnySchemaModel, item: unknown, options?: SchemaMarkdownOptions): string;
+/**
+ * Generate markdown summary statistics for numeric fields in array data.
+ */
+export declare function schemaToMarkdownSummary(items: unknown[], options?: {
+    numericFields?: string[];
+    countByField?: string;
+}): string;

package/dist/schema-to-markdown.js

@@ -0,0 +1,10 @@
+import{isSchemaModel as M}from"@lssm/lib.schema/SchemaModel";export function schemaToMarkdown(n,e,s={}){const{format:i="auto",title:o,description:l,maxDepth:r=2}=s,t=[];if(o)t.push(`# ${o}`,"");if(l)t.push(`> ${l}`,"");const c=i==="auto"?Array.isArray(e)?"table":"detail":i;if(c==="table"&&Array.isArray(e))t.push(schemaToMarkdownTable(n,e,s));else if(c==="list"&&Array.isArray(e))t.push(schemaToMarkdownList(n,e,s));else if(!Array.isArray(e)&&e!==null&&typeof e==="object")t.push(schemaToMarkdownDetail(n,e,{...s,maxDepth:r}));else t.push(`**Data:** ${String(e)}`,"");return t.join(`
+`)}export function schemaToMarkdownTable(n,e,s={}){const{maxItems:i=100,includeFields:o,excludeFields:l=[]}=s,r=b(n,o,l);if(r.length===0||e.length===0)return`_No data available_
+`;const t=e.slice(0,i),c=[],a=r.map((f)=>f.label);c.push(`| ${a.join(" | ")} |`);c.push(`| ${a.map(()=>"---").join(" | ")} |`);for(const f of t){const u=r.map((d)=>p(g(f,d.name)));c.push(`| ${u.join(" | ")} |`)}if(e.length>i)c.push("",`_Showing ${i} of ${e.length} items_`);c.push("");return c.join(`
+`)}export function schemaToMarkdownList(n,e,s={}){const{maxItems:i=50,summaryFields:o,includeFields:l,excludeFields:r=[]}=s,t=b(n,l,r),c=o?t.filter((u)=>o.includes(u.name)):t.slice(0,3);if(c.length===0||e.length===0)return`_No data available_
+`;const a=e.slice(0,i),f=[];for(const u of a){const d=p(g(u,c[0]?.name??"id")),w=c.slice(1).map((k)=>`${k.label}: ${p(g(u,k.name))}`).join(" \xB7 "),S=w?`- **${d}** (${w})`:`- **${d}**`;f.push(S)}if(e.length>i)f.push("",`_Showing ${i} of ${e.length} items_`);f.push("");return f.join(`
+`)}export function schemaToMarkdownDetail(n,e,s={}){const{includeFields:i,excludeFields:o=[],maxDepth:l=2}=s;if(e===null||typeof e!=="object")return`_No data available_
+`;const r=b(n,i,o);if(r.length===0)return`_No fields to display_
+`;const t=[];for(const c of r){const a=g(e,c.name),f=j(a,l,0);t.push(`**${c.label}:** ${f}`)}t.push("");return t.join(`
+`)}export function schemaToMarkdownSummary(n,e={}){const{numericFields:s=[],countByField:i}=e,o=[];o.push(`**Total Items:** ${n.length}`);for(const l of s){const r=n.map((t)=>g(t,l)).filter((t)=>typeof t==="number");if(r.length>0){const t=r.reduce((u,d)=>u+d,0),c=t/r.length,a=Math.min(...r),f=Math.max(...r);o.push(`**${y(l)}:** Sum: ${m(t)}, Avg: ${m(c)}, Min: ${m(a)}, Max: ${m(f)}`)}}if(i){const l={};for(const r of n){const t=String(g(r,i)??"Unknown");l[t]=(l[t]??0)+1}o.push("",`**By ${y(i)}:**`);for(const[r,t]of Object.entries(l))o.push(`- ${r}: ${t}`)}o.push("");return o.join(`
+`)}function b(n,e,s=[]){if(!M(n))return[];const i=n.config.fields;return Object.keys(i).filter((r)=>{if(s.includes(r))return!1;if(e&&!e.includes(r))return!1;return!0}).map((r)=>{const t=i[r],c=Boolean(t?.type&&typeof t.type==="object"&&"config"in t.type&&typeof t.type.config?.fields==="object");return{name:r,label:y(r),isOptional:t?.isOptional??!1,isArray:t?.isArray===!0,isNested:c}})}function g(n,e){if(n===null||typeof n!=="object")return;const s=n;if(e.includes(".")){const i=e.split(".");let o=s;for(const l of i){if(o===null||typeof o!=="object")return;o=o[l]}return o}return s[e]}function p(n){if(n===null||n===void 0)return"-";if(typeof n==="boolean")return n?"\u2713":"\u2717";if(typeof n==="number")return m(n);if(n instanceof Date)return h(n);if(typeof n==="string"&&F(n))return h(new Date(n));if(Array.isArray(n))return`[${n.length} items]`;if(typeof n==="object")return"[Object]";const e=String(n);return e.length>50?`${e.slice(0,47)}...`:e.replace(/\|/g,"\\|")}function j(n,e,s){if(n===null||n===void 0)return"_none_";if(typeof n==="boolean")return n?"Yes":"No";if(typeof n==="number")return m(n);if(n instanceof Date)return h(n);if(typeof n==="string"&&F(n))return h(new Date(n));if(Array.isArray(n)){if(n.length===0)return"_empty list_";if(s>=e)return`[${n.length} items]`;if(n.length<=5&&n.every((i)=>typeof i!=="object"))return n.map((i)=>p(i)).join(", ");return`[${n.length} items]`}if(typeof n==="object"){if(s>=e)return"[Object]";return`{${Object.keys(n).length} fields}`}return String(n)}function y(n){return n.replace(/([a-z])([A-Z])/g,"$1 $2").replace(/_/g," ").replace(/^\w/,(e)=>e.toUpperCase())}function m(n){if(Math.abs(n)>=1000)return new Intl.NumberFormat("en-US",{maximumFractionDigits:2}).format(n);if(Number.isInteger(n))return String(n);return n.toFixed(2)}function h(n){return n.toLocaleDateString("en-US",{year:"numeric",month:"short",day:"numeric"})}function F(n){if(!/^\d{4}-\d{2}-\d{2}/.test(n))return!1;const e=new Date(n);return!isNaN(e.getTime())}

package/dist/self-improving-system/constants.d.ts

@@ -0,0 +1,14 @@
+export declare const SELF_IMPROVING_SYSTEM_DOMAIN = "self-improving-system";
+export declare const SELF_IMPROVING_SYSTEM_API_VERSION = "v1";
+export declare const SELF_IMPROVING_SYSTEM_BASE_PATH = "/api/self-improvement/v1";
+export declare const SELF_IMPROVING_SYSTEM_OWNERS: readonly ['team-intelligence-platform'];
+export declare const SELF_IMPROVING_SYSTEM_TAGS: readonly ['self-improvement', 'governed-learning', 'exact-replay'];
+export declare const SELF_IMPROVING_SYSTEM_STABILITY: "experimental";
+export declare const SELF_IMPROVING_SYSTEM_CAPABILITY: {
+    readonly key: 'self-improving-system.core';
+    readonly version: '1.0.0';
+};
+export declare const SELF_IMPROVEMENT_AUTONOMY_LEVELS: readonly ['observe', 'recommend', 'plan', 'apply_with_approval', 'auto_apply_qualified'];
+export declare const SELF_IMPROVEMENT_CANDIDATE_KINDS: readonly ['runtime_artifact', 'repository_work_item'];
+export declare const SELF_IMPROVEMENT_STATUSES: readonly ['queued', 'proposing', 'evaluating', 'awaiting_approval', 'shadow', 'canary', 'observing', 'promoted', 'rejected', 'rolled_back', 'killed', 'expired', 'failed'];
+export declare const SELF_IMPROVEMENT_PROTECTED_TARGETS: readonly ['contract', 'schema', 'row_level_security', 'retention', 'deletion', 'legal_policy', 'restricted_field', 'source_admission', 'credential_policy', 'network_policy', 'provider_qualification', 'code', 'infrastructure'];

package/dist/self-improving-system/constants.js

@@ -0,0 +1 @@
+import{StabilityEnum as e}from"../ownership.js";export const SELF_IMPROVING_SYSTEM_DOMAIN="self-improving-system";export const SELF_IMPROVING_SYSTEM_API_VERSION="v1";export const SELF_IMPROVING_SYSTEM_BASE_PATH="/api/self-improvement/v1";export const SELF_IMPROVING_SYSTEM_OWNERS=["team-intelligence-platform"];export const SELF_IMPROVING_SYSTEM_TAGS=["self-improvement","governed-learning","exact-replay"];export const SELF_IMPROVING_SYSTEM_STABILITY=e.Experimental;export const SELF_IMPROVING_SYSTEM_CAPABILITY={key:"self-improving-system.core",version:"1.0.0"};export const SELF_IMPROVEMENT_AUTONOMY_LEVELS=["observe","recommend","plan","apply_with_approval","auto_apply_qualified"];export const SELF_IMPROVEMENT_CANDIDATE_KINDS=["runtime_artifact","repository_work_item"];export const SELF_IMPROVEMENT_STATUSES=["queued","proposing","evaluating","awaiting_approval","shadow","canary","observing","promoted","rejected","rolled_back","killed","expired","failed"];export const SELF_IMPROVEMENT_PROTECTED_TARGETS=["contract","schema","row_level_security","retention","deletion","legal_policy","restricted_field","source_admission","credential_policy","network_policy","provider_qualification","code","infrastructure"];