dna-sdk 0.1.0

package/dist/kernel/kind-registry.d.ts

@@ -0,0 +1,183 @@
+/**
+ * KindRegistry — the kernel's registered-Kind identity map + the full
+ * registration funnel, extracted from the Kernel god-object (kernel
+ * decomposition, Fase 3 — `s-kernel-decomp-ts-parity`; Py twin:
+ * `dna/kernel/kind_registry.py`).
+ *
+ * Two surfaces live here:
+ *
+ * - **Lookup** (pre-F3): the `kinds` map + the read surface (port lookup,
+ *   alias, storage/container resolution, container→kind, describe). Also
+ *   exported as the PURE functions `kindPortForOver` / `resolveDepFilterTargetOver`
+ *   so a registry VIEW over an existing map (CompositionEngine / nav_kernel /
+ *   the ManifestInstance) shares the ONE canonical resolver without holding a
+ *   class instance.
+ * - **Registration** (this slice): `registerKind` (the H1 validation funnel —
+ *   interface/dup-key/dup-alias/BUNDLE-marker/plane/i-195-name-collision +
+ *   alias generation), the static `_lintPlane` helper, `registerFromDescriptor`
+ *   (builtin `*.kind.yaml` descriptors) and `registerKindDefinitions` (the
+ *   per-scope KindDefinition funnel — warn+skip instead of throw). The kernel
+ *   keeps `kind()` / `kindFromDescriptor()` / `_registerKindDefinitions()` /
+ *   `_registerCustomKinds()` as THIN facades delegating here.
+ *
+ * Registration mutates `this.kinds` directly (the registry OWNS the map; the
+ * kernel's `_kinds` getter proxies to it, so the ~20 inline `this._kinds` read
+ * sites across the kernel keep working unchanged). Side effects that touch the
+ * wider kernel — hooks (`kinddef_conflict` / `parse_error` events), the
+ * `_readers` list (the rescan return gate), the generic reader/writer wiring,
+ * the `_genericsResolved` flag, and the `_loadingExtOwner` alias-owner context —
+ * route through a NARROW `RegistryHost` back-ref (the anti-cosmetic rule, spec
+ * §3.1): the kernel satisfies it structurally. View-only registries pass no host
+ * and use only the lookup surface / pure functions.
+ *
+ * One registry per kernel, shared across `withTenant` shallow copies (Kinds are
+ * global — registered once at boot on the base kernel).
+ *
+ * The map is keyed `${apiVersion}\0${kind}` — the same shape held by both the
+ * Kernel and the ManifestInstance.
+ */
+import type { KindPort, StorageDescriptor } from "./protocols.js";
+import type { RegistryHost } from "./collaborator-ports.js";
+/**
+ * Resolve a kind's prose documentation.
+ *
+ * Resolution order:
+ *   1. DOCS-<KindName>.md next to the extension's source file
+ *      (inside `<basename>/`, where basename is the extension .ts stem)
+ *   2. DOCS.md in that same directory
+ *   3. The `docs` attribute on the KindPort
+ *   4. null
+ *
+ * Browser consumers (Tauri Studio / Vite) stub node:fs/path/url via
+ * `nodeStubPlugin` in vite.config.ts — filesystem reads return empty and
+ * the loader transparently falls through to `kp.docs`.
+ */
+export declare function loadKindDocs(kp: KindPort): string | null;
+/** CamelCase kind name → kebab-case: EvalCase → eval-case, ADR → adr,
+ *  HTMLThing → html-thing. */
+export declare function kebabKindName(kind: string): string;
+/** The canonical alias for a Kind: `<owner>-<kebab(kind)>`. */
+export declare function generateAlias(owner: string, kind: string): string;
+/** Ratchet (shrink-only): every builtin CLASS Kind that still hand-types
+ *  its alias — the live wire format that CANNOT be renamed without a doc
+ *  migration. New Kinds must OMIT the alias (generation). Entries leave
+ *  as classes migrate to generation/descriptors — NEVER add one
+ *  (tests/alias-generation.test.ts, ratchet test). Py twin:
+ *  dna.kernel.kind_registry.EXPLICIT_ALIAS_ALLOWLIST — the TS set
+ *  excludes the Py-only extensions (gaia-*, collab-comment) and includes
+ *  every TS class port, per kind-registry-parity.json. */
+export declare const EXPLICIT_ALIAS_ALLOWLIST: ReadonlySet<string>;
+/** i-195 — kind names allowed to exist under MULTIPLE apiVersions in the
+ *  extension/builtin funnel. SHRINK-ONLY ratchet: the Reference pair
+ *  (github.com/ruinosus/dna/research/v1 + github.com/ruinosus/dna/sdlc/v1) predates the guard and is scheduled
+ *  to be merged by the Reference-family unification follow-up; when that
+ *  lands, empty this set. NEVER add a name here — rename the new Kind
+ *  instead (bare-name lookups become ambiguous the moment two
+ *  apiVersions share a kind name). Py twin:
+ *  dna.kernel.kind_registry.KIND_NAME_COLLISION_ALLOWLIST. */
+export declare const KIND_NAME_COLLISION_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Lookup a registered KindPort by kind name (case-sensitive) over `kinds`.
+ * With `apiVersion` the lookup is EXACT on (apiVersion, kind) — bare
+ * lookups on a name shared by multiple apiVersions resolve
+ * extension-first then registration order (i-195, Py twin:
+ * `KindRegistry.port_for`).
+ */
+export declare function kindPortForOver(kinds: Map<string, KindPort>, kind: string, apiVersion?: string): KindPort | null;
+/**
+ * Canonical dep_filter target resolution (s-alias-generated-not-typed).
+ *
+ * The CONTRACT is alias-valued dep_filters (`"soulspec-soul"`). The
+ * legacy `"kind=<Name>"` format resolves through a DEPRECATED shim so
+ * per-scope KindDefinition docs keep working (builtin extensions must be
+ * alias-pure — `validateDepFilters` rejects `kind=` there). Since
+ * s-unify-composition-subsystems this is THE resolver for every
+ * dep_filter reader — `validateRefs` / `mi.composition` and the Kernel.
+ * Py twin: `KindRegistry.resolve_dep_filter_target`.
+ */
+export declare function resolveDepFilterTargetOver(kinds: Map<string, KindPort>, value: string): KindPort | null;
+/**
+ * Holds the registered KindPorts + the lookups + the registration funnel.
+ */
+export declare class KindRegistry {
+    /** Key: "apiVersion\0kind" for uniqueness. OWNED here; the kernel's
+     *  `_kinds` getter proxies to it. */
+    readonly kinds: Map<string, KindPort>;
+    /** The NARROW `RegistryHost` back-ref used ONLY by the registration
+     *  funnel (hooks fan-out, the `_readers` rescan gate, generic
+     *  reader/writer wiring, `_genericsResolved`, the `_loadingExtOwner`
+     *  alias-owner context). Only read at registration time (boot) — so the
+     *  kernel may pass `this` before its `hooks`/`_readers` are fully wired.
+     *  View-only registries pass `null` and never call `register*`. */
+    private readonly _host;
+    constructor(kinds?: Map<string, KindPort>, host?: RegistryHost | null);
+    /** Lookup a registered KindPort by kind name (case-sensitive). With
+     *  apiVersion the lookup is EXACT on (apiVersion, kind); bare lookups on
+     *  an ambiguous name resolve extension-first then registration order
+     *  (i-195). Py twin: `KindRegistry.port_for`. */
+    portFor(kind: string, apiVersion?: string): KindPort | null;
+    /** All registered KindPorts. Order matches registration. */
+    allPorts(): KindPort[];
+    /** Resolve a kind name to its globally-unique alias (`<owner>-<kind>`).
+     *  Falls back to `kind.toLowerCase()` when no registered port provides
+     *  one. Py twin: `KindRegistry.alias_for`. */
+    aliasFor(kind: string, apiVersion?: string): string;
+    /** Return the storage container directory for a kind, or null. */
+    containerFor(kindName: string): string | null;
+    /** Return the StorageDescriptor for a kind, or null if unknown. */
+    storageFor(kindName: string): StorageDescriptor | null;
+    /** Return the kind name whose StorageDescriptor.container matches.
+     *  null for empty container (ROOT kinds) or unregistered containers. */
+    byContainer(container: string): string | null;
+    /** Canonical dep_filter target resolution (s-alias-generated-not-typed).
+     *  Delegates to the shared `resolveDepFilterTargetOver`. Py twin:
+     *  `KindRegistry.resolve_dep_filter_target`. */
+    resolveDepFilterTarget(value: string): KindPort | null;
+    /** Summary dict for a registered kind, including resolved docs. Py twin:
+     *  `KindRegistry.describe`. */
+    describe(kindName: string): Record<string, unknown> | null;
+    /** s-alias-generated-not-typed — every dep_filter target of an
+     *  EXTENSION-registered Kind must resolve to a registered alias.
+     *
+     *  Aliases are the wire key of dep_filters / Mustache sections /
+     *  LayerPolicy — a typo used to degrade the prompt SILENTLY (the dep
+     *  just vanished from the context, warning buried in logs). Called at
+     *  the end of `loadBuiltins()` (the TS twin of `Kernel.auto()`).
+     *
+     *  - Extension/builtin port with an unknown alias OR the legacy
+     *    `kind=` format → `KindRegistrationError` (boot fails loud).
+     *  - Per-scope declarative ports (user KindDefinition docs) only WARN
+     *    — user docs never take the boot down (same posture as the
+     *    parse_error / plane-lint funnels).
+     *  Py twin: `KindRegistry.validate_dep_filters`. */
+    validateDepFilters(): void;
+    /** H1 registration funnel — moved verbatim from `Kernel.kind()`. The
+     *  kernel keeps `kind()` as a thin facade delegating here. Py twin:
+     *  `KindRegistry.register_kind`. */
+    registerKind(k: KindPort): void;
+    /** Two-planes lint (spec D1) — plane is explicit and validated, never
+     *  derived. A "record" Kind cannot carry any composition signal;
+     *  contradictions fail registration loudly instead of silently
+     *  mis-routing the write path.
+     *
+     *  F3 (spec D3): extracted from `registerKind()` so BOTH funnels run it —
+     *  `registerKind()` (extension classes + builtin descriptors) throws;
+     *  `registerKindDefinitions` (per-scope) catches → warn + skip
+     *  (per-scope docs never take the boot down). Mirrors Python
+     *  KindRegistry._lint_plane. */
+    static _lintPlane(k: KindPort): void;
+    /** F3 (spec D3): register a BUILTIN Kind from a KindDefinition
+     *  descriptor (`kinds/*.kind.yaml` package data). Same format + same
+     *  funnel as everything else. Py twin:
+     *  `KindRegistry.register_from_descriptor`. */
+    registerFromDescriptor(raw: Record<string, unknown>): KindPort;
+    /** Phase 1 of 2-phase loading: parse KindDefinition docs + register
+     *  synthetic DeclarativeKindPorts. Extension-registered kinds win on
+     *  conflict. Returns true iff new BUNDLE readers were added (the rescan
+     *  gate). Py twin: `KindRegistry.register_kind_definitions`. */
+    registerKindDefinitions(rawDocs: Record<string, unknown>[]): boolean;
+    /** Register dynamic kinds from `Module.spec.custom_kinds`. Py twin:
+     *  `KindRegistry.register_custom_kinds`. */
+    registerCustomKinds(manifest: Record<string, unknown>): void;
+    static _makeDynamicKind(av: string, kn: string, al: string): KindPort;
+}