@lssm/lib.contracts 0.0.0-canary-20251217052941 → 0.0.0-canary-20251217060433

package/dist/presentations.v2.d.ts

@@ -0,0 +1,114 @@
+import { OwnerShipMeta } from "./ownership.js";
+import { DocId } from "./docs/registry.js";
+import { AnySchemaModel } from "@lssm/lib.schema";
+import React from "react";
+import { BlockConfig } from "@blocknote/core";
+
+//#region src/presentations.v2.d.ts
+/** Supported render targets for the transform engine and descriptors. */
+type PresentationTarget = 'react' | 'markdown' | 'application/json' | 'application/xml';
+interface PresentationV2Meta extends Partial<OwnerShipMeta> {
+  /** Fully-qualified presentation name (e.g., "sigil.auth.webauth_tabs_v2"). */
+  name: string;
+  /** Version of this descriptor. Increment on breaking changes. */
+  version: number;
+  /** Human-readable description for docs/a11y. Required by validators. */
+  description?: string;
+  /** Optional doc block id for this presentation. */
+  docId?: DocId;
+}
+/** React component presentation source. */
+interface PresentationSourceComponentReact {
+  /** Source marker for React component presentations. */
+  type: 'component';
+  /** Framework for the component source (currently only 'react'). */
+  framework: 'react';
+  /** Component key resolved by host `componentMap`. */
+  componentKey: string;
+  /** Optional props schema to validate against. */
+  props?: AnySchemaModel;
+}
+/** BlockNoteJS document presentation source. */
+interface PresentationSourceBlocknotejs {
+  /** Source marker for BlockNoteJS document presentations. */
+  type: 'blocknotejs';
+  /** BlockNoteJS JSON document. */
+  docJson: unknown;
+  /** Optional BlockNote config to guide rendering. */
+  blockConfig?: BlockConfig;
+}
+type PresentationSource = PresentationSourceComponentReact | PresentationSourceBlocknotejs;
+/**
+ * Normalized presentation descriptor decoupled from framework/adapters.
+ * Renderers and validators are provided via TransformEngine.
+ */
+interface PresentationDescriptorV2 {
+  meta: PresentationV2Meta;
+  policy?: {
+    flags?: string[];
+    pii?: string[];
+  };
+  source: PresentationSource;
+  targets: PresentationTarget[];
+}
+interface RenderContext {
+  /** Optional locale hint (i18n). */
+  locale?: string;
+  /** Enabled feature flags to drive conditional rendering. */
+  featureFlags?: string[];
+  /** Redaction hook for custom PII handling. */
+  redact?: (path: string, value: unknown) => unknown;
+  /** Optional data for schema-driven rendering (arrays or objects). */
+  data?: unknown;
+  /** Optional async data fetcher for renderers that need to load data on demand. */
+  fetchData?: () => Promise<unknown>;
+}
+interface PresentationRenderer<TOut> {
+  target: PresentationTarget;
+  render: (desc: PresentationDescriptorV2, ctx?: RenderContext) => Promise<TOut>;
+}
+interface PresentationValidator {
+  validate: (desc: PresentationDescriptorV2, target: PresentationTarget, ctx?: RenderContext) => Promise<void> | void;
+}
+declare class TransformEngine {
+  private renderers;
+  private validators;
+  register<TOut>(renderer: PresentationRenderer<TOut>): this;
+  /**
+   * Register a renderer that will be tried BEFORE existing renderers for the same target.
+   * Useful for custom renderers that should take priority over default ones.
+   */
+  prependRegister<TOut>(renderer: PresentationRenderer<TOut>): this;
+  addValidator(v: PresentationValidator): this;
+  render<TOut = unknown>(target: PresentationTarget, desc: PresentationDescriptorV2, ctx?: RenderContext): Promise<TOut>;
+}
+/** Create a TransformEngine instance with default markdown/json/xml renderers. */
+declare function createDefaultTransformEngine(): TransformEngine;
+/** Serializable render descriptor for React hosts. */
+type ReactRenderDescriptor = {
+  kind: 'react_component';
+  componentKey: string;
+  props?: Record<string, unknown>;
+} | {
+  kind: 'blocknotejs';
+  docJson: unknown;
+  blockConfig?: BlockConfig;
+};
+/** Register a default React target renderer that returns a serializable descriptor. */
+declare function registerDefaultReactRenderer(engine: TransformEngine): TransformEngine;
+/**
+ * Add basic validators (e.g., meta.description presence) to the engine.
+ */
+declare function registerBasicValidation(engine: TransformEngine): TransformEngine;
+/**
+ * Component map type for React rendering.
+ */
+type ComponentMap = Record<string, React.ComponentType<any>>;
+/**
+ * Register a React-to-markdown renderer that renders React components to HTML
+ * and converts them to markdown using turndown.
+ * This renderer takes priority over the default metadata-only renderer.
+ */
+declare function registerReactToMarkdownRenderer(engine: TransformEngine, componentMap: ComponentMap): TransformEngine;
+//#endregion
+export { ComponentMap, PresentationDescriptorV2, PresentationRenderer, PresentationSource, PresentationSourceBlocknotejs, PresentationSourceComponentReact, PresentationTarget, PresentationV2Meta, PresentationValidator, ReactRenderDescriptor, RenderContext, TransformEngine, createDefaultTransformEngine, registerBasicValidation, registerDefaultReactRenderer, registerReactToMarkdownRenderer };

package/dist/prompt.d.ts

@@ -0,0 +1,60 @@
+import * as z$1 from "zod";
+
+//#region src/prompt.d.ts
+type PromptStability = 'experimental' | 'beta' | 'stable' | 'deprecated';
+/** Parameter definition for a prompt argument. */
+interface PromptArg {
+  name: string;
+  description?: string;
+  required?: boolean;
+  schema: z$1.ZodType;
+  completeWith?: string;
+}
+/**
+ * Rendered content part for a prompt. Clients (MCP) can fetch referenced resources.
+ */
+type PromptContentPart = {
+  type: 'text';
+  text: string;
+} | {
+  type: 'resource';
+  uri: string;
+  title?: string;
+};
+/** Prompt metadata for discoverability and governance. */
+interface PromptMeta {
+  name: string;
+  version: number;
+  title: string;
+  description: string;
+  tags?: string[];
+  stability?: PromptStability;
+  owners?: string[];
+}
+/** Policy constraints for prompts (flags, PII paths, rate limits). */
+interface PromptPolicy {
+  flags?: string[];
+  pii?: string[];
+  rateLimit?: {
+    rpm: number;
+    key: 'user' | 'org' | 'global';
+  };
+}
+/** Full prompt specification including args schema and render function. */
+interface PromptSpec<I extends z$1.ZodType> {
+  meta: PromptMeta;
+  args: PromptArg[];
+  input: I;
+  policy?: PromptPolicy;
+  /** Render MCP-friendly content parts. DO NOT perform side effects here. */
+  render: (args: z$1.infer<I>, ctx: {
+    userId?: string | null;
+    orgId?: string | null;
+    locale?: string;
+    link: (template: string, vars: Record<string, string | number>) => string;
+  }) => Promise<PromptContentPart[]>;
+}
+/** Identity helper that preserves generic inference when declaring prompts. */
+declare function definePrompt<I extends z$1.ZodType>(spec: PromptSpec<I>): PromptSpec<I>;
+//#endregion
+export { PromptArg, PromptContentPart, PromptMeta, PromptPolicy, PromptSpec, PromptStability, definePrompt };

package/dist/promptRegistry.d.ts

@@ -0,0 +1,15 @@
+import { PromptSpec } from "./prompt.js";
+import * as z$1 from "zod";
+
+//#region src/promptRegistry.d.ts
+declare class PromptRegistry {
+  private prompts;
+  /** Register a prompt. Throws on duplicate name+version. */
+  register<I extends z$1.ZodType>(p: PromptSpec<I>): this;
+  /** List all registered prompts. */
+  list(): PromptSpec<any>[];
+  /** Get prompt by name; when version omitted, returns highest version. */
+  get(name: string, version?: number): PromptSpec<any> | undefined;
+}
+//#endregion
+export { PromptRegistry };

package/dist/regenerator/adapters.d.ts

@@ -0,0 +1,19 @@
+import { BehaviorSignal, ErrorSignal, RegenerationContext, TelemetrySignal } from "./types.js";
+
+//#region src/regenerator/adapters.d.ts
+interface TelemetrySignalProvider {
+  pollTelemetry(context: RegenerationContext, since: Date, until: Date): Promise<TelemetrySignal[]>;
+}
+interface ErrorSignalProvider {
+  pollErrors(context: RegenerationContext, since: Date, until: Date): Promise<ErrorSignal[]>;
+}
+interface BehaviorSignalProvider {
+  pollBehavior(context: RegenerationContext, since: Date, until: Date): Promise<BehaviorSignal[]>;
+}
+interface SignalAdapters {
+  telemetry?: TelemetrySignalProvider;
+  errors?: ErrorSignalProvider;
+  behavior?: BehaviorSignalProvider;
+}
+//#endregion
+export { BehaviorSignalProvider, ErrorSignalProvider, SignalAdapters, TelemetrySignalProvider };

package/dist/regenerator/docs/regenerator.docblock.d.ts

@@ -0,0 +1,6 @@
+import { DocBlock } from "@lssm/lib.contracts/docs";
+
+//#region src/regenerator/docs/regenerator.docblock.d.ts
+declare const tech_contracts_regenerator_DocBlocks: DocBlock[];
+//#endregion
+export { tech_contracts_regenerator_DocBlocks };

package/dist/regenerator/executor.d.ts

@@ -0,0 +1,70 @@
+import { ProposalAction, RegenerationContext, SpecChangeProposal } from "./types.js";
+
+//#region src/regenerator/executor.d.ts
+type ExecutionStatus = 'success' | 'skipped' | 'failed';
+interface ActionExecutionResult {
+  index: number;
+  action: ProposalAction;
+  status: ExecutionStatus;
+  startedAt: Date;
+  finishedAt: Date;
+  reason?: string;
+  error?: Error;
+  output?: unknown;
+}
+interface ProposalExecutionResult {
+  proposalId: string;
+  contextId: string;
+  startedAt: Date;
+  finishedAt: Date;
+  status: 'success' | 'partial' | 'failed';
+  actions: ActionExecutionResult[];
+}
+type UpdateBlueprintAction = Extract<ProposalAction, {
+  kind: 'update_blueprint';
+}>;
+type UpdateTenantConfigAction = Extract<ProposalAction, {
+  kind: 'update_tenant_config';
+}>;
+type RunTestsAction = Extract<ProposalAction, {
+  kind: 'run_tests';
+}>;
+type RunMigrationsAction = Extract<ProposalAction, {
+  kind: 'run_migrations';
+}>;
+type TriggerRegenerationAction = Extract<ProposalAction, {
+  kind: 'trigger_regeneration';
+}>;
+interface BlueprintUpdater {
+  applyBlueprintUpdate(context: RegenerationContext, proposal: SpecChangeProposal, action: UpdateBlueprintAction): Promise<unknown>;
+}
+interface TenantConfigUpdater {
+  applyTenantConfigUpdate(context: RegenerationContext, proposal: SpecChangeProposal, action: UpdateTenantConfigAction): Promise<unknown>;
+}
+interface TestExecutor {
+  runTests(context: RegenerationContext, proposal: SpecChangeProposal, action: RunTestsAction): Promise<unknown>;
+}
+interface MigrationExecutor {
+  runMigrations(context: RegenerationContext, proposal: SpecChangeProposal, action: RunMigrationsAction): Promise<unknown>;
+}
+interface RegenerationTrigger {
+  triggerRegeneration(context: RegenerationContext, proposal: SpecChangeProposal, action: TriggerRegenerationAction): Promise<unknown>;
+}
+interface ProposalExecutorOptions {
+  dryRun?: boolean;
+}
+interface ProposalExecutorDeps {
+  blueprintUpdater?: BlueprintUpdater;
+  tenantConfigUpdater?: TenantConfigUpdater;
+  testExecutor?: TestExecutor;
+  migrationExecutor?: MigrationExecutor;
+  regenerationTrigger?: RegenerationTrigger;
+}
+declare class ProposalExecutor {
+  private readonly deps;
+  constructor(deps?: ProposalExecutorDeps);
+  execute(context: RegenerationContext, proposal: SpecChangeProposal, options?: ProposalExecutorOptions): Promise<ProposalExecutionResult>;
+  private executeAction;
+}
+//#endregion
+export { ActionExecutionResult, BlueprintUpdater, ExecutionStatus, MigrationExecutor, ProposalExecutionResult, ProposalExecutor, ProposalExecutorDeps, ProposalExecutorOptions, RegenerationTrigger, RunMigrationsAction, RunTestsAction, TenantConfigUpdater, TestExecutor, TriggerRegenerationAction, UpdateBlueprintAction, UpdateTenantConfigAction };

package/dist/regenerator/index.d.ts

@@ -0,0 +1,7 @@
+import { BehaviorSignal, BehaviorSignalEnvelope, ErrorSignal, ErrorSignalEnvelope, ProposalAction, ProposalBlocker, ProposalConfidence, ProposalSink, ProposalTarget, RegenerationContext, RegenerationRule, RegeneratorSignal, SpecChangeProposal, TelemetrySignal, TelemetrySignalEnvelope } from "./types.js";
+import { BehaviorSignalProvider, ErrorSignalProvider, SignalAdapters, TelemetrySignalProvider } from "./adapters.js";
+import { RegeneratorOptions, RegeneratorService } from "./service.js";
+import { ActionExecutionResult, BlueprintUpdater, ExecutionStatus, MigrationExecutor, ProposalExecutionResult, ProposalExecutor, ProposalExecutorDeps, ProposalExecutorOptions, RegenerationTrigger, RunMigrationsAction, RunTestsAction, TenantConfigUpdater, TestExecutor, TriggerRegenerationAction, UpdateBlueprintAction, UpdateTenantConfigAction } from "./executor.js";
+import { behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope } from "./utils.js";
+import { ExecutorProposalSink, ExecutorResultPayload, ExecutorSinkLogger, ExecutorSinkOptions } from "./sinks.js";
+export { ActionExecutionResult, BehaviorSignal, BehaviorSignalEnvelope, BehaviorSignalProvider, BlueprintUpdater, ErrorSignal, ErrorSignalEnvelope, ErrorSignalProvider, ExecutionStatus, ExecutorProposalSink, ExecutorResultPayload, ExecutorSinkLogger, ExecutorSinkOptions, MigrationExecutor, ProposalAction, ProposalBlocker, ProposalConfidence, ProposalExecutionResult, ProposalExecutor, ProposalExecutorDeps, ProposalExecutorOptions, ProposalSink, ProposalTarget, RegenerationContext, RegenerationRule, RegenerationTrigger, RegeneratorOptions, RegeneratorService, RegeneratorSignal, RunMigrationsAction, RunTestsAction, SignalAdapters, SpecChangeProposal, TelemetrySignal, TelemetrySignalEnvelope, TelemetrySignalProvider, TenantConfigUpdater, TestExecutor, TriggerRegenerationAction, UpdateBlueprintAction, UpdateTenantConfigAction, behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope };

package/dist/regenerator/service.d.ts

@@ -0,0 +1,33 @@
+import { ProposalSink, RegenerationContext, RegenerationRule } from "./types.js";
+import { SignalAdapters } from "./adapters.js";
+
+//#region src/regenerator/service.d.ts
+interface RegeneratorOptions {
+  contexts: RegenerationContext[];
+  adapters: SignalAdapters;
+  rules: RegenerationRule[];
+  sink: ProposalSink;
+  pollIntervalMs?: number;
+  batchDurationMs?: number;
+  clock?: () => Date;
+}
+declare class RegeneratorService {
+  private readonly options;
+  private readonly contexts;
+  private readonly lastPoll;
+  private timer?;
+  private running;
+  private readonly pollInterval;
+  private readonly batchDuration;
+  private readonly clock;
+  constructor(options: RegeneratorOptions);
+  start(): void;
+  stop(): void;
+  runOnce(): Promise<void>;
+  private tick;
+  private evaluateContext;
+  private collectSignals;
+  private flushProposals;
+}
+//#endregion
+export { RegeneratorOptions, RegeneratorService };

package/dist/regenerator/sinks.d.ts

@@ -0,0 +1,26 @@
+import { ProposalSink, RegenerationContext, SpecChangeProposal } from "./types.js";
+import { ProposalExecutionResult, ProposalExecutor } from "./executor.js";
+
+//#region src/regenerator/sinks.d.ts
+interface ExecutorResultPayload {
+  context: RegenerationContext;
+  proposal: SpecChangeProposal;
+  result: ProposalExecutionResult;
+}
+interface ExecutorSinkLogger {
+  info?: (message: string, meta?: Record<string, unknown>) => void;
+  error?: (message: string, error: Error, meta?: Record<string, unknown>) => void;
+}
+interface ExecutorSinkOptions {
+  dryRun?: boolean;
+  onResult?: (payload: ExecutorResultPayload) => void | Promise<void>;
+  logger?: ExecutorSinkLogger;
+}
+declare class ExecutorProposalSink implements ProposalSink {
+  private readonly executor;
+  private readonly options;
+  constructor(executor: ProposalExecutor, options?: ExecutorSinkOptions);
+  submit(context: RegenerationContext, proposal: SpecChangeProposal): Promise<void>;
+}
+//#endregion
+export { ExecutorProposalSink, ExecutorResultPayload, ExecutorSinkLogger, ExecutorSinkOptions };

package/dist/regenerator/types.d.ts

@@ -0,0 +1,107 @@
+import { TelemetrySpec } from "../telemetry/spec.js";
+import { AppBlueprintSpec, TenantAppConfig } from "../app-config/spec.js";
+import { ResolvedAppConfig } from "../app-config/runtime.js";
+
+//#region src/regenerator/types.d.ts
+type RegeneratorSignal = TelemetrySignalEnvelope | ErrorSignalEnvelope | BehaviorSignalEnvelope;
+interface TelemetrySignalEnvelope {
+  type: 'telemetry';
+  contextId: string;
+  signal: TelemetrySignal;
+}
+interface TelemetrySignal {
+  eventName: string;
+  eventVersion: number;
+  count: number;
+  windowStart: Date;
+  windowEnd: Date;
+  anomalyScore?: number;
+  classification?: 'normal' | 'warning' | 'critical';
+  metadata?: Record<string, unknown>;
+  telemetrySpec?: TelemetrySpec;
+}
+interface ErrorSignalEnvelope {
+  type: 'error';
+  contextId: string;
+  signal: ErrorSignal;
+}
+interface ErrorSignal {
+  id: string;
+  classification: 'runtime' | 'policy' | 'workflow' | 'unknown';
+  message: string;
+  occurredAt: Date;
+  count: number;
+  metadata?: Record<string, unknown>;
+}
+interface BehaviorSignalEnvelope {
+  type: 'behavior';
+  contextId: string;
+  signal: BehaviorSignal;
+}
+interface BehaviorSignal {
+  feature: string;
+  metric: 'usage' | 'conversion' | 'latency' | 'custom';
+  value: number;
+  baseline?: number;
+  windowStart: Date;
+  windowEnd: Date;
+  metadata?: Record<string, unknown>;
+}
+interface SpecChangeProposal {
+  id: string;
+  title: string;
+  summary: string;
+  confidence: ProposalConfidence;
+  rationale: string[];
+  target: ProposalTarget;
+  diff?: string;
+  actions: ProposalAction[];
+  blockers?: ProposalBlocker[];
+  createdAt: Date;
+  signalIds: string[];
+}
+type ProposalConfidence = 'low' | 'medium' | 'high';
+interface ProposalTarget {
+  specType: 'workflow' | 'capability' | 'policy' | 'dataView' | 'telemetry' | 'experiment' | 'theme' | 'unknown';
+  reference: {
+    name: string;
+    version?: number;
+  };
+  tenantScoped?: boolean;
+}
+type ProposalAction = {
+  kind: 'update_blueprint';
+  summary: string;
+} | {
+  kind: 'update_tenant_config';
+  summary: string;
+} | {
+  kind: 'run_tests';
+  tests: string[];
+} | {
+  kind: 'run_migrations';
+  migrations: string[];
+} | {
+  kind: 'trigger_regeneration';
+  summary?: string;
+};
+interface ProposalBlocker {
+  description: string;
+  kind: 'missing_context' | 'insufficient_data' | 'user_feedback' | 'manual_review';
+}
+interface RegenerationContext {
+  id: string;
+  blueprint: AppBlueprintSpec;
+  tenantConfig: TenantAppConfig;
+  resolved: ResolvedAppConfig;
+}
+interface RegenerationRule {
+  readonly id: string;
+  readonly description: string;
+  evaluate(context: RegenerationContext, signals: RegeneratorSignal[]): Promise<SpecChangeProposal[]>;
+}
+interface ProposalSink {
+  submit(context: RegenerationContext, proposal: SpecChangeProposal): Promise<void>;
+}
+//#endregion
+export { BehaviorSignal, BehaviorSignalEnvelope, ErrorSignal, ErrorSignalEnvelope, ProposalAction, ProposalBlocker, ProposalConfidence, ProposalSink, ProposalTarget, RegenerationContext, RegenerationRule, RegeneratorSignal, SpecChangeProposal, TelemetrySignal, TelemetrySignalEnvelope };

package/dist/regenerator/utils.d.ts

@@ -0,0 +1,9 @@
+import { BehaviorSignal, BehaviorSignalEnvelope, ErrorSignal, ErrorSignalEnvelope, TelemetrySignal, TelemetrySignalEnvelope } from "./types.js";
+
+//#region src/regenerator/utils.d.ts
+type Clock = () => Date;
+declare function telemetryToEnvelope(contextId: string, signal: TelemetrySignal, clock: Clock): TelemetrySignalEnvelope;
+declare function errorToEnvelope(contextId: string, signal: ErrorSignal, clock: Clock): ErrorSignalEnvelope;
+declare function behaviorToEnvelope(contextId: string, signal: BehaviorSignal, clock: Clock): BehaviorSignalEnvelope;
+//#endregion
+export { behaviorToEnvelope, errorToEnvelope, telemetryToEnvelope };

package/dist/registry.d.ts

@@ -0,0 +1,73 @@
+import { defaultDocRegistry, docId, registerDocBlocks } from "./docs/registry.js";
+import { ResourceRefDescriptor } from "./resources.js";
+import { ContractSpec } from "./spec.js";
+import { HandlerCtx } from "./types.js";
+import { HandlerFor } from "./install.js";
+import { AnySchemaModel } from "@lssm/lib.schema";
+
+//#region src/registry.d.ts
+
+type OperationKey = `${string}.v${number}`;
+declare function opKey(name: string, version: number): OperationKey;
+type AnySpec = ContractSpec<AnySchemaModel, AnySchemaModel | ResourceRefDescriptor<boolean>>;
+type AnyHandler = (args: any, ctx: HandlerCtx) => Promise<unknown>;
+/**
+ * In-memory registry for ContractSpecs and their bound handlers.
+ * Provides validation, policy enforcement, and guarded event emission at execute time.
+ */
+declare class SpecRegistry {
+  private specs;
+  private handlers;
+  /**
+   * Registers a ContractSpec definition.
+   *
+   * @param spec - The contract specification to register.
+   * @returns The registry instance for chaining.
+   * @throws If a spec with the same name and version is already registered.
+   */
+  register<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: ContractSpec<I, O>): this;
+  /**
+   * Binds a runtime handler implementation to a previously registered spec.
+   *
+   * @param spec - The spec to bind to.
+   * @param handler - The async function implementing the business logic.
+   * @returns The registry instance for chaining.
+   * @throws If the spec is not found or a handler is already bound.
+   */
+  bind<I extends AnySchemaModel, O extends AnySchemaModel | ResourceRefDescriptor<boolean>>(spec: ContractSpec<I, O>, handler: HandlerFor<ContractSpec<I, O>>): this;
+  /**
+   * Retrieves a registered spec by name and version.
+   * If version is omitted, returns the highest version found.
+   *
+   * @param name - Operation name.
+   * @param version - (Optional) Specific version.
+   */
+  getSpec(name: string, version?: number): AnySpec | undefined;
+  /**
+   * Retrieves the bound handler for a spec.
+   */
+  getHandler(name: string, version?: number): AnyHandler | undefined;
+  /** Iterate all registered specs. */
+  listSpecs(): AnySpec[];
+  /** Iterate all bound operations (spec+handler). */
+  listBound(): {
+    spec: AnySpec;
+    handler: AnyHandler;
+  }[];
+  /**
+   * Execute an operation by name/version with full runtime protections:
+   * 1. Validates input against Zod schema.
+   * 2. Enforces policy (Auth, RBAC, Rate Limits) via PDP.
+   * 3. Guards event emission to ensure only declared events are sent.
+   * 4. Validates output against Zod schema (if applicable).
+   * 5. Tracks telemetry (success/failure).
+   *
+   * @param name - Operation name.
+   * @param version - Operation version (optional, defaults to latest).
+   * @param rawInput - The raw input payload (e.g. from JSON body).
+   * @param ctx - The runtime context (actor, tenant, etc.).
+   */
+  execute(name: string, version: number | undefined, rawInput: unknown, ctx: HandlerCtx): Promise<unknown>;
+}
+//#endregion
+export { OperationKey, SpecRegistry, defaultDocRegistry, docId, opKey, registerDocBlocks };

package/dist/resources.d.ts

@@ -0,0 +1,64 @@
+import { Tag } from "./ownership.js";
+import * as z$1 from "zod";
+
+//#region src/resources.d.ts
+interface ResourceMeta {
+  /** URI scheme, e.g. "content://doc/{id}" or "marketplace://offers/{city}/{tag}" */
+  uriTemplate: string;
+  /** Human title for discovery */
+  title: string;
+  /** Short description */
+  description?: string;
+  /** MIME type for resource body */
+  mimeType: string;
+  /** Tags for filtering/grouping */
+  tags?: Tag[];
+}
+interface ResourceTemplateSpec<I extends z$1.ZodType> {
+  meta: ResourceMeta;
+  /** Arguments to materialize the URI (zod validates input) */
+  input: I;
+  /**
+   * Resolve returns the resource body and a resolved URI.
+   * It MUST be read-only (no side effects).
+   */
+  resolve: (args: z$1.infer<I>, ctx: {
+    userId?: string | null;
+    orgId?: string | null;
+    locale?: string;
+  }) => Promise<{
+    uri: string;
+    mimeType?: string;
+    data: Uint8Array | string;
+  }>;
+}
+declare function defineResourceTemplate<I extends z$1.ZodType>(spec: ResourceTemplateSpec<I>): ResourceTemplateSpec<I>;
+declare class ResourceRegistry {
+  private templates;
+  register<I extends z$1.ZodType>(tmpl: ResourceTemplateSpec<I>): this;
+  listTemplates(): ResourceTemplateSpec<any>[];
+  /** Try to match a concrete URI to a template by naive pattern substitution */
+  match(uri: string): {
+    tmpl: ResourceTemplateSpec<any>;
+    params: Record<string, string>;
+  } | undefined;
+}
+interface ResourceRefDescriptor<Many extends boolean> {
+  kind: 'resource_ref';
+  /** URI template, e.g. 'strit://spot/{id}' */
+  uriTemplate: string;
+  /** Variable name inside result payload to substitute into template; defaults to 'id' */
+  varName?: string;
+  /** Optional GraphQL type name to use when exposing over GraphQL (e.g., 'Spot') */
+  graphQLType: string;
+  /** Cardinality: when present and true, the handler returns an array of resources */
+  many: Many;
+}
+declare function resourceRef<Many extends boolean>(uriTemplate: string, opts: {
+  varName?: string;
+  graphQLType: string;
+  many: Many;
+}): ResourceRefDescriptor<Many>;
+declare function isResourceRef(x: unknown): x is ResourceRefDescriptor<boolean>;
+//#endregion
+export { ResourceMeta, ResourceRefDescriptor, ResourceRegistry, ResourceTemplateSpec, defineResourceTemplate, isResourceRef, resourceRef };

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

@@ -0,0 +1,54 @@
+import { AnySchemaModel } from "@lssm/lib.schema";
+
+//#region src/schema-to-markdown.d.ts
+
+/**
+ * Options for schema-to-markdown generation
+ */
+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.
+ */
+declare function schemaToMarkdown(schema: AnySchemaModel, data: unknown, options?: SchemaMarkdownOptions): string;
+/**
+ * Generate a markdown table from array data using schema fields as columns.
+ */
+declare function schemaToMarkdownTable(schema: AnySchemaModel, items: unknown[], options?: SchemaMarkdownOptions): string;
+/**
+ * Generate a markdown list from array data.
+ * Uses summaryFields to create concise list items.
+ */
+declare function schemaToMarkdownList(schema: AnySchemaModel, items: unknown[], options?: SchemaMarkdownOptions): string;
+/**
+ * Generate a markdown detail view (key-value pairs) from object data.
+ */
+declare function schemaToMarkdownDetail(schema: AnySchemaModel, item: unknown, options?: SchemaMarkdownOptions): string;
+/**
+ * Generate markdown summary statistics for numeric fields in array data.
+ */
+declare function schemaToMarkdownSummary(schema: AnySchemaModel, items: unknown[], options?: {
+  numericFields?: string[];
+  countByField?: string;
+}): string;
+//#endregion
+export { SchemaMarkdownOptions, schemaToMarkdown, schemaToMarkdownDetail, schemaToMarkdownList, schemaToMarkdownSummary, schemaToMarkdownTable };