@ai-matrx/alchemy 0.5.1 → 0.6.0

package/dist/declare.d.ts

@@ -0,0 +1,334 @@
+/**
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
+ *
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** Unchanged from `ui_surface_value_type_chk`. */
+type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
+type Classification = "ordinary" | "secret" | "credential";
+/** Persisted (CONTRACT §2.7). Projection enforces it before any value leaves. */
+interface Sensitivity {
+    /** false = never leaves through Operate. Default true. */
+    exportable: boolean;
+    /** secret/credential are always excluded; no caller can relax this. Default "ordinary". */
+    classification: Classification;
+    /** Pre-checked in the preparation workspace. Default true. */
+    includedByDefault: boolean;
+}
+interface ValueGroup {
+    key: string;
+    label: string;
+    sortOrder: number;
+    description?: string;
+}
+/** The four runtime slots a capture fills (absorbs page-capture). */
+type LiveSlot = "selection" | "on-demand" | "errors" | "requests";
+interface DeclaredValue {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    /** Registered content-ir kind key (DB: kind_key). */
+    valueKind?: string;
+    alwaysAvailable: boolean;
+    typicalCharCount: number;
+    autoContext?: boolean;
+    group?: string;
+    sortOrder?: number;
+    sensitivity?: Partial<Sensitivity>;
+    /** Filled at capture time from a live slot instead of the scope. */
+    liveSlot?: LiveSlot;
+    /** "request" values drop out of "Only the data". Default "data". */
+    role?: "data" | "request";
+}
+/** Where a write lands. "stream" = applied live, op by op, into an editable text. */
+type WriteMode = "draft" | "entity" | "ui" | "stream";
+/** Who may apply WITHOUT a click. "queued" = filed for an organization's review. */
+type ApplyPolicy = "manual" | "ask" | "auto" | "queued";
+/** The WidgetHandle text op set, unchanged in meaning. */
+type StreamOp = "replace" | "insert_before" | "insert_after" | "prepend" | "append" | "patch";
+interface WriteTarget {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    valueKind?: string;
+    /** Read twin (evidence loop). Required when patchable or mode === "stream". */
+    updatesValue?: string;
+    patchable?: boolean;
+    approvalComparison?: "text-replacement";
+    mode: WriteMode;
+    /** Required iff mode === "stream". */
+    streamOps?: readonly StreamOp[];
+    /** Default "manual". Binding overrides may only tighten. */
+    applyPolicy?: ApplyPolicy;
+    destination?: boolean;
+    /** Present when the target writes into an item rather than the screen. */
+    itemType?: string;
+    group?: string;
+    sortOrder?: number;
+}
+/** One kind of thing inside a screen (a row, a message, a code block, a card). */
+interface ItemType {
+    name: string;
+    label: string;
+    description: string;
+    /** Value names that together identify one item. */
+    identity: readonly string[];
+    levels?: readonly string[];
+    entityType?: string;
+    values: readonly DeclaredValue[];
+    writeTargets?: readonly WriteTarget[];
+}
+type Readiness = "verified" | "partial" | "stub";
+/** `ui_surface_execution_mode_check`, unchanged. */
+type ExecutionMode = "python-stream" | "nextjs-stream" | "browser-realtime" | "local-runtime";
+interface ConfigNamespaceDeclaration {
+    namespace: string;
+    label: string;
+    description: string;
+}
+interface EvidenceSourceDeclaration {
+    kind: "processed_document";
+    idValue: string;
+    fileIdValue?: string;
+    labelValue?: string;
+    representation?: "clean" | "raw";
+}
+/**
+ * One screen's declaration. Owning packages add fields (agent roles, client
+ * tools) as EXTENSION SLOTS — by interface extension or declaration merging —
+ * and register a `DeclarationExtension` so validation and the sync cover them.
+ */
+interface SurfaceDeclaration {
+    surfaceName: string;
+    /** REQUIRED. `ui_surface.client_name`; must equal the surfaceName prefix. */
+    client: string;
+    /** REQUIRED. `ui_surface.execution_mode`. */
+    executionMode: ExecutionMode;
+    /** REQUIRED. `ui_surface.description` ("" only where the live row is empty). */
+    description: string;
+    label: string;
+    readiness: Readiness;
+    readinessNote?: string;
+    urlPattern?: string;
+    inheritsFrom?: string;
+    intro?: string;
+    overlayId?: string;
+    values: readonly DeclaredValue[];
+    groups?: readonly ValueGroup[];
+    writeTargets?: readonly WriteTarget[];
+    itemTypes?: readonly ItemType[];
+    liveSlots?: readonly LiveSlot[];
+    configNamespaces?: readonly ConfigNamespaceDeclaration[];
+    evidenceSources?: readonly EvidenceSourceDeclaration[];
+    skipBaselineValues?: boolean;
+}
+interface DeclarationIssue {
+    surfaceName: string;
+    /** "writeTargets/body/updatesValue" */
+    path: string;
+    sentence: string;
+    remedy: string;
+    /** Advisory issues are reported, never fatal (the ratchets). Default "error". */
+    severity?: "error" | "advisory";
+}
+/** A row the sync writes for an extension slot (e.g. agent roles, client tools). */
+interface ExtensionRow {
+    table: string;
+    /** The row's key columns within its table (e.g. ["surface_name", "name"]). */
+    conflict: readonly string[];
+    row: Record<string, Json>;
+}
+interface DeclarationExtension<D extends SurfaceDeclaration = SurfaceDeclaration> {
+    key: string;
+    /** Package or app that owns the slot, shown in check failures. */
+    owner: string;
+    /**
+     * Lists this slot contributes to inheritance: a child inherits its parent's
+     * entries and overrides per identity (child wins).
+     */
+    inheritedLists?: readonly {
+        field: string;
+        identity(entry: unknown): string;
+    }[];
+    validate?(declaration: D, context: ValidationContext): readonly DeclarationIssue[];
+    toRows?(declaration: D): readonly ExtensionRow[];
+}
+interface ValidationContext {
+    /** Every registered declaration, resolved. */
+    all: readonly ResolvedSurfaceDeclaration[];
+}
+type ValueProvenance = {
+    kind: "own";
+} | {
+    kind: "inherited";
+    from: string;
+} | {
+    kind: "baseline";
+};
+type ResolvedValue = DeclaredValue & {
+    provenance: ValueProvenance;
+    groupKey: string;
+    /** Defaults filled. */
+    resolvedSensitivity: Sensitivity;
+};
+interface ResolvedSurfaceDeclaration extends SurfaceDeclaration {
+    contentHash: string;
+    values: readonly ResolvedValue[];
+    groups: readonly ValueGroup[];
+}
+/**
+ * ITEM KEYS. A value or write target is identified by (surfaceName, itemType ?? "", name).
+ * The qualified key "<itemType>.<name>" names an item value; a bare name is a screen value.
+ */
+type QualifiedValueKey = string;
+/** Live slot payloads (page-capture's shapes, kept). */
+interface LiveValues {
+    selection?: {
+        choices: Record<string, Json>;
+        text: string | null;
+    };
+    "on-demand"?: readonly OnDemandSection[];
+    errors?: readonly string[];
+    requests?: readonly RecentRequest[];
+}
+interface OnDemandSection {
+    id: string;
+    title: string;
+    description?: string;
+    role: "data" | "request";
+    brief?: Json;
+    load(signal: AbortSignal): Promise<Json>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json;
+    requestBodyNote?: string;
+    errorSentence?: string;
+    timestamp: number;
+}
+/** RAW-FREE. What leaves the package about a clicked item. */
+interface ResolvedItem {
+    itemType: string;
+    identity: Record<string, string>;
+    level?: string;
+    readOnly: boolean;
+}
+
+/** Every value, write-target, item-type and group name (the DB CHECK rule). */
+declare const DECLARATION_NAME_RE: RegExp;
+/** "<client>/<local>" — the surface naming convention. */
+declare const SURFACE_NAME_RE: RegExp;
+/** A bare screen value (`status`) or an item value (`table_row.status`). */
+declare const QUALIFIED_VALUE_KEY_RE: RegExp;
+interface ParsedValueKey {
+    /** "" for a screen-level value. */
+    itemType: string;
+    name: string;
+}
+/** Split a qualified key; null when it is not a valid bare or qualified key. */
+declare function parseQualifiedValueKey(key: string): ParsedValueKey | null;
+declare function qualifyValueKey(itemType: string, name: string): QualifiedValueKey;
+/** The client that owns a surface: its name prefix. */
+declare function surfaceClientOf(surfaceName: string): string;
+
+/** Canonical JSON: keys sorted, undefined dropped, arrays in order. */
+declare function canonicalJson(value: unknown): string;
+/** SHA-256 hex of a UTF-8 string. Pure, synchronous, runs anywhere (no crypto API needed). */
+declare function sha256Hex(input: string): string;
+/**
+ * Drift between clients. Computed, never authored: SHA-256 of the canonical JSON
+ * of the declaration as authored (keys sorted, extension fields included).
+ * Persisted as `ui_surface.content_hash` once that column exists.
+ */
+declare function declarationHash(declaration: SurfaceDeclaration): string;
+
+declare const VALUE_TYPES: readonly ["string", "number", "boolean", "object", "array", "document"];
+declare const WRITE_MODES: readonly ["draft", "entity", "ui", "stream"];
+declare const APPLY_POLICIES: readonly ["manual", "ask", "auto", "queued"];
+declare const STREAM_OPS: readonly ["replace", "insert_before", "insert_after", "prepend", "append", "patch"];
+declare const EXECUTION_MODES: readonly ["python-stream", "nextjs-stream", "browser-realtime", "local-runtime"];
+declare const READINESS: readonly ["verified", "partial", "stub"];
+declare const LIVE_SLOTS: readonly ["selection", "on-demand", "errors", "requests"];
+declare const CLASSIFICATIONS: readonly ["ordinary", "secret", "credential"];
+interface ValidateOptions {
+    /** Registered config namespaces; omitted = not checked. */
+    knownNamespaces?: ReadonlySet<string>;
+    /** Registered content-ir kind slugs; omitted = not checked. */
+    isKnownKind?: (slug: string) => boolean;
+    /** Names every declaration must expose unless `skipBaselineValues`. */
+    baselineNames?: readonly string[];
+    extensions?: readonly DeclarationExtension[];
+}
+declare function validateDeclarations(declarations: readonly ResolvedSurfaceDeclaration[], options?: ValidateOptions): DeclarationIssue[];
+/**
+ * The runtime half: a loaded scope may carry only declared values. Returns one
+ * issue per undeclared key (and per `__item` value its item type does not declare).
+ */
+declare function validateLoadedValues(declaration: Pick<ResolvedSurfaceDeclaration, "surfaceName" | "values" | "itemTypes">, loaded: Record<string, unknown>, options?: {
+    ignore?: readonly string[];
+}): DeclarationIssue[];
+/**
+ * Ownership: no `ui.ui_surface` row may exist without a declaring owner
+ * (CONTRACT §2.1a). `retired` rows (archived, not deleted) are exempt.
+ */
+declare function findOrphanRows(rowNames: readonly string[], declaredNames: Iterable<string>, retired?: Iterable<string>): string[];
+
+declare const RESERVED_GROUP_KEYS: {
+    readonly general: "general";
+    readonly baseline: "baseline";
+    readonly inheritedPrefix: "inherited:";
+};
+/** Group sortOrder bands. Curated groups author 0–899; the rest is reserved. */
+declare const GENERAL_GROUP_ORDER = 850;
+declare const INHERITED_GROUP_ORDER_BASE = 9000;
+declare const BASELINE_GROUP_ORDER = 9900;
+declare const DEFAULT_MAX_INHERITANCE_DEPTH = 3;
+declare const DEFAULT_SENSITIVITY: Sensitivity;
+declare function resolveSensitivity(value: Pick<DeclaredValue, "sensitivity">): Sensitivity;
+type Resolved<D extends SurfaceDeclaration> = Omit<D, "values" | "groups"> & {
+    values: readonly (D["values"][number] & ResolvedValue)[];
+    groups: readonly ValueGroup[];
+    contentHash: string;
+};
+interface DeclarationRegistryOptions {
+    /** Generic values injected into every declaration unless `skipBaselineValues`. */
+    baselineValues?: readonly DeclaredValue[];
+    /** Value names only the platform writes; a declaration claiming one is refused. */
+    reservedValueNames?: readonly string[];
+    /** Write-target names only the platform writes. */
+    reservedWriteTargetNames?: readonly string[];
+    maxInheritanceDepth?: number;
+}
+interface DeclarationRegistry<D extends SurfaceDeclaration> {
+    /** Refuses a second declaration of the same surfaceName. */
+    register(declaration: D): void;
+    registerExtension(extension: DeclarationExtension<D>): void;
+    extensions(): readonly DeclarationExtension<D>[];
+    /** Declarations exactly as authored (inheritance unresolved, no baselines). */
+    raw(): readonly D[];
+    getRaw(surfaceName: string): D | undefined;
+    /** Parent chain, ROOT FIRST. Unknown surfaces return []. */
+    ancestry(surfaceName: string): string[];
+    /** Direct children (declarations naming it in `inheritsFrom`), in declaration order. */
+    children(surfaceName: string): string[];
+    /** Inheritance + baseline + groups resolved; provenance kept. */
+    all(): readonly Resolved<D>[];
+    get(surfaceName: string): Resolved<D> | undefined;
+    validate(options?: ValidateOptions): readonly DeclarationIssue[];
+}
+declare function createDeclarationRegistry<D extends SurfaceDeclaration>(options?: DeclarationRegistryOptions): DeclarationRegistry<D>;
+
+export { APPLY_POLICIES, type ApplyPolicy, BASELINE_GROUP_ORDER, CLASSIFICATIONS, type Classification, type ConfigNamespaceDeclaration, DECLARATION_NAME_RE, DEFAULT_MAX_INHERITANCE_DEPTH, DEFAULT_SENSITIVITY, type DeclarationExtension, type DeclarationIssue, type DeclarationRegistry, type DeclarationRegistryOptions, type DeclaredValue, EXECUTION_MODES, type EvidenceSourceDeclaration, type ExecutionMode, type ExtensionRow, GENERAL_GROUP_ORDER, INHERITED_GROUP_ORDER_BASE, type ItemType, type Json, LIVE_SLOTS, type LiveSlot, type LiveValues, type OnDemandSection, type ParsedValueKey, QUALIFIED_VALUE_KEY_RE, type QualifiedValueKey, READINESS, RESERVED_GROUP_KEYS, type Readiness, type RecentRequest, type Resolved, type ResolvedItem, type ResolvedSurfaceDeclaration, type ResolvedValue, STREAM_OPS, SURFACE_NAME_RE, type Sensitivity, type StreamOp, type SurfaceDeclaration, VALUE_TYPES, type ValidateOptions, type ValidationContext, type ValueGroup, type ValueProvenance, type ValueType, WRITE_MODES, type WriteMode, type WriteTarget, canonicalJson, createDeclarationRegistry, declarationHash, findOrphanRows, parseQualifiedValueKey, qualifyValueKey, resolveSensitivity, sha256Hex, surfaceClientOf, validateDeclarations, validateLoadedValues };