dna-sdk 0.1.0

package/dist/kernel/composition-resolver.d.ts

@@ -0,0 +1,215 @@
+/**
+ * The kernel's unified composition motor — TS twin of
+ * `packages/sdk-py/dna/kernel/composition_resolver.py`
+ * (s-unify-composition-subsystems). One module, four composition
+ * concerns:
+ *
+ *   1. CompositionProfile (V1) — declarative wiring + UI hints
+ *      registered by extensions (moved here from `composition.ts`,
+ *      now a deprecated re-export shim).
+ *   2. `validateRefs` — THE shared cross-kind ref validation core;
+ *      target resolution via `resolveDepFilterTargetOver`
+ *      (kind-registry.ts) — the same canonical resolver the Kernel
+ *      uses, so alias + legacy `kind=` resolve identically everywhere.
+ *   3. CompositionEngine — the `mi.composition` namespace (moved here
+ *      from `composition-engine.ts`, deleted).
+ *   4. CompositionResolver — the Composition-V2 chain-resolution engine.
+ *
+ * Pure resolution types + merges stay in `resolver.ts` (Py:
+ * `kernel/resolver.py`).
+ *
+ * Record-plane rule (two-planes F2.5) — ONE rule for every reader: a ref
+ * whose TARGET Kind is plane="record" resolves when present in the doc
+ * index and is DEFERRED otherwise (never false-missing).
+ *
+ * # CompositionResolver — Composition-V2 (Phase 17 /
+ * s-ts-composition-v2-port).
+ *
+ * Behavior parity is 1:1 with the Python engine on the RESOLUTION SEMANTICS:
+ * chain walk (`computeResolutionChain` — cycle guard + MAX_RESOLUTION_DEPTH +
+ * V1 fallback to `_lib`), composition-rule lookup (`getCompositionRule` —
+ * LayerPolicy.composition_rules else the inherit-by-default denylist),
+ * `resolveDocument` (bootstrap bypass, tenant overlay, Catalog splice
+ * Local > Catalog > Base, override_full / field_level merge, provenance) and
+ * `personalizeDocument`. The behavioral gate is the shared fixture harness
+ * `tests/parity-fixtures/composition/` (s-parity-behavioral-harness), executed
+ * by BOTH `packages/sdk-py/tests/test_composition_parity_fixtures.py` and
+ * `packages/sdk-ts/tests/composition-parity-fixtures.test.ts`.
+ *
+ * Documented divergences from Python — PERF / infra, NOT semantics:
+ *
+ * 1. **No granular layer cache.** The Py kernel reads each layer through
+ *    `_granular_doc_cached` (LRU 2000 / TTL 60s / single-flight). The TS
+ *    kernel has no kernel-level doc cache, so `Kernel._granularDoc` hits the
+ *    source directly on every layer read. Same inputs → same outputs; each
+ *    resolve just costs O(chain) source reads instead of cache hits.
+ * 2. **No `_layer_observers` reverse-dep graph.** That structure exists purely
+ *    to invalidate the Py granular cache across scopes on parent/catalog
+ *    writes; with no cache there is nothing to invalidate. It is intentionally
+ *    NOT ported (would be dead state).
+ * 3. **Catalog tier surface.** The TS kernel has no catalog machinery yet
+ *    (package scan + tenant lockfile — deferred as `i-185`). The splice HOOK
+ *    is fully implemented here (identical to Py: insert after the local
+ *    entries, before the first parent, conflict surfacing on ≥2 hits) but
+ *    `Kernel._catalogScopes` returns `[]` until i-185 lands, so the Catalog
+ *    tier contributes no layers on TS today.
+ * 4. **`personalizeDocument` clones spec + envelope only.** The Py engine also
+ *    clones binary bundle entries via `source._load_bundle_entries` +
+ *    `kernel.write_bundle_entry_async`; the TS kernel has no bundle-entry
+ *    write surface yet, so bundle payload cloning is Py-only (best-effort in
+ *    Py anyway — failures there are swallowed).
+ */
+import { ResolvedDocument } from "./resolver.js";
+import type { CompositionResolverHost } from "./collaborator-ports.js";
+import type { Document } from "./document.js";
+import type { CompositionResult, KindPort } from "./protocols.js";
+import type { ManifestInstance } from "./instance.js";
+/** Timeline rendering hints for a composition slot. */
+export interface TimelineHint {
+    readonly label: string;
+    readonly itemLabel: string;
+}
+/** Health check rule for a composition slot. */
+export interface HealthCheckHint {
+    /** "at-least-one": agent must reference ≥1 doc of this slot.
+     *  "has-error-severity": at least one doc of this kind with
+     *  severity=error must be referenced. */
+    readonly rule: "at-least-one" | "has-error-severity";
+    readonly severity: "warn" | "error";
+    /** Key in the health report output dict. e.g. "agents_without_guardrails". */
+    readonly issueKey: string;
+    /** Human message for the issue. */
+    readonly message: string;
+}
+/** Quadrant chart configuration for a composition slot. */
+export interface QuadrantHint {
+    readonly axis: "x" | "y";
+    /** Axis label. e.g. "Few Skills --> Many Skills". */
+    readonly label: string;
+    /** Divide doc count by this to normalize to 0..1 range. */
+    readonly maxScale: number;
+}
+/**
+ * A named slot in a composition profile. Each slot describes how an
+ * orchestrator kind connects to a target kind.
+ */
+export interface CompositionSlot {
+    /** The spec field name on the orchestrator that holds refs to this kind.
+     *  e.g. "skills", "soul", "guardrails". */
+    readonly name: string;
+    /** Alias of the target KindPort. e.g. "agentskills-skill". */
+    readonly targetAlias: string;
+    /** "one" = scalar ref (soul), "many" = array ref (skills, guardrails). */
+    readonly cardinality: "one" | "many";
+    /** Rendering order in timeline diagrams. Lower = earlier. */
+    readonly order: number;
+    /** If true, buildPrompt callers can filter this slot via enabledSlots. */
+    readonly filterable: boolean;
+    /** Timeline rendering hints. Null = skip this slot in timelines. */
+    readonly timeline: TimelineHint | null;
+    /** Health check rule. Null = no health check for this slot. */
+    readonly healthCheck: HealthCheckHint | null;
+    /** Quadrant chart configuration. Null = not plotted. */
+    readonly quadrant: QuadrantHint | null;
+}
+/**
+ * A CompositionProfile describes how an orchestrator kind connects to
+ * other kinds. Registered by extensions via kernel.compositionProfile().
+ */
+export interface CompositionProfile {
+    /** Alias of the orchestrator KindPort. e.g. "helix-agent". */
+    readonly orchestratorAlias: string;
+    /** Human-readable label for the profile. e.g. "Helix Agent". */
+    readonly label: string;
+    /** Ordered list of composition slots. */
+    readonly slots: readonly CompositionSlot[];
+}
+/**
+ * Find the profile whose orchestrator matches a given alias.
+ * Returns null if none registered. Pure helper — no kernel dependency.
+ */
+export declare function profileForOrchestrator(profiles: readonly CompositionProfile[], orchestratorAlias: string): CompositionProfile | null;
+/**
+ * Validate declared dep_filter refs of `docs` against `docIndex`
+ * (`${kind}\0${name}` keys). The ONE implementation behind
+ * `mi.composition.validate()` — target resolution via
+ * `resolveDepFilterTargetOver` (canonical s-alias resolver: alias
+ * contract + deprecated `kind=` shim). Unresolvable target → warnings;
+ * ref in index → resolved; absent + record-plane target → deferred
+ * (records resolve lazily via the kernel record plane — never
+ * false-missing); absent otherwise → missing.
+ * Py twin: `composition_resolver.validate_refs`.
+ */
+export declare function validateRefs(docs: Iterable<Document>, docIndex: Set<string>, kinds: Map<string, KindPort>): CompositionResult;
+export declare class CompositionEngine {
+    private host;
+    constructor(host: ManifestInstance);
+    /**
+     * Validate all composition references over the MI plane.
+     * Equivalent to `mi.compositionResult`. Delegates to `validateRefs` —
+     * records are excluded from the MI materialization, so record-target
+     * refs land in `deferred` (they resolve lazily via the kernel record
+     * plane at read time).
+     */
+    validate(): CompositionResult;
+    /**
+     * Iterate a document's declared dep_filters dynamically.
+     * Equivalent to `mi.iterDocDeps(doc)`.
+     */
+    iterDocDeps(doc: Document): {
+        label: string;
+        targetKind: string;
+        names: string[];
+    }[];
+    /**
+     * Walk the manifest and return every doc that references this one.
+     * Equivalent to `mi.consumersOf(kind, name)`.
+     */
+    consumersOf(kind: string, name: string): Array<{
+        kind: string;
+        name: string;
+    }>;
+    /**
+     * Build a dependency tree for the manifest.
+     * Equivalent to `mi.dependencyTree()`.
+     */
+    dependencyTree(): Record<string, unknown>;
+}
+export declare class CompositionResolver {
+    private readonly _k;
+    constructor(kernel: CompositionResolverHost);
+    /**
+     * Walk `Genome.spec.parent_scope` transitively → ordered chain of
+     * `[scope, tenant]` pairs, HIGHEST priority first. Cycle-guarded; depth
+     * capped at MAX_RESOLUTION_DEPTH; missing Genome terminates the walk.
+     * 1:1 with Py `compute_resolution_chain`.
+     */
+    computeResolutionChain(scope: string, tenant: string | null): Promise<Array<[string, string | null]>>;
+    /**
+     * Resolve `[scope_inheritance, merge_strategy, tenant_overlay]` for
+     * (scope, kind) — from the scope's LayerPolicy composition_rules, else
+     * the inherit-by-default denylist (everything inherits from _lib except
+     * the per-scope ledger + structural Kinds). 1:1 with Py
+     * `get_composition_rule`.
+     */
+    getCompositionRule(scope: string, kind: string): Promise<[string, string, string]>;
+    /**
+     * Resolve a doc through the composition chain (Phase 17). Returns a
+     * ResolvedDocument with merged doc + full provenance. Bootstrap Kinds
+     * bypass inheritance (local-only). 1:1 with Py `resolve_document`.
+     */
+    resolveDocument(scope: string, kind: string, name: string, opts?: {
+        tenant?: string | null;
+    }): Promise<ResolvedDocument>;
+    /**
+     * Clone an inherited doc into `targetScope` as a local override
+     * (Phase 17). Throws if the doc isn't inherited / target exists (without
+     * overwrite). Clones spec + envelope atomically via `writeDocument`.
+     * 1:1 with Py `personalize_document` EXCEPT bundle-entry payload cloning
+     * (Py-only — see divergence #4 in the module docstring).
+     */
+    personalizeDocument(targetScope: string, kind: string, name: string, opts?: {
+        tenant?: string | null;
+        overwrite?: boolean;
+    }): Promise<ResolvedDocument>;
+}