@avantf/dsh-plugin-base 0.3.1

package/dist/interface.d.ts

@@ -0,0 +1,262 @@
+/**
+ * The base's INTERFACE TYPE — the named, frozen v1 surface of `@avantf/dsh-plugin-base`'s `.` entry.
+ *
+ * Plugins load the base through the inlined bootstrap and never name it by specifier at runtime; they
+ * describe what they loaded with `typeof import('@avantf/dsh-plugin-base')`, a namespace type that
+ * grows silently with every new export. This file is the other half: named types an author can hold in
+ * their head, stating which members are the contract and what each one means. The compiler checks them
+ * structurally against the real module in `test/public-surface.spec.ts`, and the cross-tree behaviour
+ * tests in `mem/packages/plugin/test/interface.spec.ts` / `work/packages/plugin/test/interface.spec.ts`
+ * drive the SAME members from a base that is actually linked — because the semantic half of the
+ * contract (which directory a path resolves to, what `ensure` guarantees, what a refusal says) cannot
+ * be caught by a type.
+ *
+ * The surface has TWO halves and they are named separately because they are checked differently:
+ *
+ *  - {@link BaseRuntimeV1} — the VALUE members. A real module can be structurally assigned to it, so
+ *    a missing or reshaped value member is a compile error, and `keyof` matches the runtime exports.
+ *  - {@link BaseTypeSurfaceV1} — the TYPES a caller names when using those members (types are erased,
+ *    so no runtime value can carry them). `keyof` is the type-name list.
+ *
+ * `VALUE_NAMES_V1` and `TYPE_NAMES_V1` are the same two lists as data, because the snapshot gate needs
+ * to compare string sets. The gate asserts they are exactly the two `keyof`s, so a member can never be
+ * added to the interface and forgotten in the snapshot (or vice versa).
+ *
+ * `INTERFACE_VERSION` is the integer the plugins bake at build time and compare against the value
+ * reported by the base they actually loaded at startup. It moves only for an INTERFACE change (the set
+ * of names below, a signature in it, or the meaning of a member) — not for a behaviour/flow change and
+ * not for a fix. The package version remains the INSTALL-time gate (the plugin's peer range); this
+ * constant is the RUNTIME one.
+ *
+ * @module @avantf/dsh-plugin-base/interface
+ */
+import type { CompatContext, CompatEvidence, CompatLine, CompatLogger, CompatReportWords, CompatSpec, CompatVerdict, ProbeOutcome, ServiceProbe } from './compat.js';
+import type { ProvisionCode } from './errors.js';
+import type { InterfaceRequirement, InterfaceVerdict } from './interface_gate.js';
+import type { DataHomeInput } from './kit/family.js';
+import type { PluginLogger, PluginLoggerHost, PluginLoggerOptions } from './kit/logger.js';
+import type { LoadedPromptText, PromptFileSpec, PromptFilesIo, PromptFilesLogger, PromptFilesOptions } from './kit/prompt_files.js';
+import type { StrictCodec } from './kit/typert.js';
+import type { EnsureOptions, InstallContext, InstallManifest, ItemPolicy, Kind, Manifest, MirrorPolicy, OnMissing, Plan, PlanEntry, PlanOptions, ProbeResult, ProgressEvent, Provider, ProviderContext, ProviderPlan, ProvisionEvent, ProvisionFs, ProvisionLock, ProvisionLogger, ProvisionPolicy, ProvisionReport, ProvisionReportEntry, ProvisionStatus, Provisioner, ProvisionerExperimental, ProvisionerOptions, PrunePolicy, PruneReport, PublishMeta, Resolved, ResourceHandle, ResourceIdentity, ResourceState, Startup } from './types.js';
+/**
+ * The integer interface generation this module implements.
+ *
+ * `1` is the first frozen generation: the surface recorded by `api/interface-v1.json`. The file name's
+ * `N` and this constant are the SAME fact — `test/public-surface.spec.ts` asserts that the snapshot for
+ * this constant exists and that its `interfaceVersion` field equals it, so "the JSON says v2, the
+ * constant says 1" cannot happen. Bump it (and add `api/interface-vN.json`) only for an interface
+ * change (INTERFACE.md §1); a behaviour change or a fix does NOT touch it. The plugins bake this number
+ * into their artifacts and compare it, at startup, with the number the base they loaded reports — a
+ * difference is a warning and a capability-level degradation, never a refused mount.
+ */
+export declare const INTERFACE_VERSION = 1;
+/**
+ * The VALUE half of the v1 `.` surface: every member that exists at runtime.
+ *
+ * Members are typed `typeof import('./x.js').name` — one reference to the source of truth, never a
+ * restated signature — so a change to an implementation's signature is a compile error where a real
+ * module is assigned to this type, not two silently disagreeing declarations. `keyof BaseRuntimeV1` is
+ * exactly the module's runtime export set (the gate asserts it against `Object.keys`).
+ *
+ * The `kit` group is the family's shared, DSH-free code: the reason a shared-helper fix needs only a
+ * base release. Plugins take those members off the module they loaded at runtime instead of inlining a
+ * copy. `resolveDataHome` takes the NAMED slot object {@link DataHomeInput}, which is the one breaking
+ * change that produced this generation.
+ */
+export interface BaseRuntimeV1 {
+    /** The interface generation; see {@link INTERFACE_VERSION}. */
+    readonly INTERFACE_VERSION: typeof INTERFACE_VERSION;
+    /** The compat log token (`compat:`) every line the gate emits begins with. */
+    readonly COMPAT_PREFIX: typeof import('./compat.js').COMPAT_PREFIX;
+    /** The baked build-record file name (`dsh-build.json`) read beside a plugin's entry. */
+    readonly BUILD_VERSIONS_FILE: typeof import('./compat.js').BUILD_VERSIONS_FILE;
+    /** The name of the throwaway tool the tools probe registers. */
+    readonly COMPAT_PROBE_TOOL: typeof import('./compat.js').COMPAT_PROBE_TOOL;
+    /** The item schema generation this build understands. */
+    readonly ITEM_SCHEMA_VERSION: typeof import('./provisioner.js').ITEM_SCHEMA_VERSION;
+    /** The default ensure deadline, in milliseconds. */
+    readonly DEFAULT_DEADLINE_MS: typeof import('./provisioner.js').DEFAULT_DEADLINE_MS;
+    /** The provisioner's capability list. */
+    readonly CAPABILITIES: typeof import('./provisioner.js').CAPABILITIES;
+    /**
+     * Decide whether a loaded module implements the interface generation a caller requires. Pure,
+     * bidirectional, guarded and total — the ONE implementation of the verdict semantics, so a fix to
+     * them is a base release and not two plugin rebuilds.
+     */
+    readonly checkInterface: typeof import('./interface_gate.js').checkInterface;
+    /**
+     * Read the `{ baseVersion, interfaceVersion }` record a plugin artifact was baked with; a missing
+     * or malformed file is `undefined` ("not baked"), never a throw.
+     */
+    readonly readInterfaceRequirement: typeof import('./interface_gate.js').readInterfaceRequirement;
+    /** Run the gate against a live context: register nothing, decide `load`, log the diagnosis. */
+    readonly provision: typeof import('./compat.js').provision;
+    /** Build the refusal report from a verdict plus the CALLER's wording. */
+    readonly compatReport: typeof import('./compat.js').compatReport;
+    /** Keep one user-visible command that reports a refusal (the only channel on that path). */
+    readonly registerMegaphone: typeof import('./compat.js').registerMegaphone;
+    /** The wire schema names a contribution declares (the post-registration check's input). */
+    readonly schemaNamesFrom: typeof import('./compat.js').schemaNamesFrom;
+    /** Confirm, after mounting, that every declared schema and tool is really registered. */
+    readonly verifyRegisteredFaces: typeof import('./compat.js').verifyRegisteredFaces;
+    /** The peer-range FLOORS of the packages that identify the host (the `declared` fallback). */
+    readonly readDeclaredVersions: typeof import('./compat.js').readDeclaredVersions;
+    /** The versions this BUILD was compiled against, baked next to the entry. */
+    readonly readBuildVersions: typeof import('./compat.js').readBuildVersions;
+    /** The versions THIS build's links resolve to at startup. */
+    readonly readRuntimeVersions: typeof import('./compat.js').readRuntimeVersions;
+    /** Build the probe tool declaration from the caller's own `defineTool`. */
+    readonly toolProbeDeclaration: typeof import('./compat.js').toolProbeDeclaration;
+    /** The rules as a pure function of evidence (no host, no I/O). */
+    readonly verdictOf: typeof import('./compat.js').verdictOf;
+    /** The lower bound one declared peer range names. */
+    readonly floorOf: typeof import('./compat.js').floorOf;
+    /** The versions THIS build's links resolve to for one package. */
+    readonly resolveRuntimeVersion: typeof import('./compat.js').resolveRuntimeVersion;
+    /** The services a live context actually exposes, against the caller's contracts. */
+    readonly checkServices: typeof import('./compat.js').checkServices;
+    /** Whether the context carries the effect-scoped timer (`ctx.interval`) the engine needs. */
+    readonly checkInterval: typeof import('./compat.js').checkInterval;
+    /** Gather the plain evidence {@link verdictOf} consumes from a live context. */
+    readonly gatherEvidence: typeof import('./compat.js').gatherEvidence;
+    /** Probe a tools registry with the caller's real declaration (`not probed` is not a break). */
+    readonly probeToolsRegistry: typeof import('./compat.js').probeToolsRegistry;
+    /** Probe the Typert registry with the caller's real wire contribution. */
+    readonly probeTypertRegistry: typeof import('./compat.js').probeTypertRegistry;
+    /** The registry keys a package's schema names become (`<packageId>#<name>`). */
+    readonly declaredSchemaKeys: typeof import('./compat.js').declaredSchemaKeys;
+    /** Ensure + read the family's user-editable prompt files. */
+    readonly PromptFiles: typeof import('./kit/prompt_files.js').PromptFiles;
+    /** Build a plugin logger with the family's line format and host mirror. */
+    readonly createPluginLogger: typeof import('./kit/logger.js').createPluginLogger;
+    /** The family root: `$AVANTF_HOME`, else `~/.avantf/env`. */
+    readonly familyHome: typeof import('./kit/family.js').familyHome;
+    /** `<family root>/tools`. */
+    readonly familyToolsDir: typeof import('./kit/family.js').familyToolsDir;
+    /** `<family root>/models`. */
+    readonly familyModelsDir: typeof import('./kit/family.js').familyModelsDir;
+    /**
+     * The DATA root, by the family's layer order: ⑤ explicit → ④ `$AVANTF_HOME` → ② the configured
+     * `dataHome` → `~/.avantf`. Every slot is NAMED ({@link DataHomeInput}) — the positional form is
+     * what let the two copies of this rule disagree about where the profile's `dataHome` belongs.
+     */
+    readonly resolveDataHome: typeof import('./kit/family.js').resolveDataHome;
+    /** `~/x` → `<home>/x`, `~` → `<home>`; anything else unchanged. */
+    readonly expandHome: typeof import('./kit/family.js').expandHome;
+    /** Build the family's Typert `<pkg>#<namespace>/<method>:<field>` wire codec. */
+    readonly strictCodec: typeof import('./kit/typert.js').strictCodec;
+    /** `<package>#<namespace>/<method>`. */
+    readonly endpointId: typeof import('./kit/typert.js').endpointId;
+    /** The type symbol of one field of one method. */
+    readonly fieldSymbol: typeof import('./kit/typert.js').fieldSymbol;
+    /** The type symbol of a method's result. */
+    readonly resultSymbol: typeof import('./kit/typert.js').resultSymbol;
+    /** Build a provisioner over a family root. */
+    readonly createProvisioner: typeof import('./provisioner.js').createProvisioner;
+    /** The policy value that normalizes an `onMissing` shorthand. */
+    readonly normalizeOnMissing: typeof import('./provisioner.js').normalizeOnMissing;
+    /** The error a failed provision throws, with its machine-readable `code`. */
+    readonly ProvisionError: typeof import('./errors.js').ProvisionError;
+    /** The machine-readable code of a provision failure. */
+    readonly reasonOf: typeof import('./errors.js').reasonOf;
+    /** The binary-archive provider factory. */
+    readonly binaryArchiveProvider: typeof import('./providers/archive.js').binaryArchiveProvider;
+    /** The binary-archive item kind. */
+    readonly BINARY_ARCHIVE_KIND: typeof import('./providers/archive.js').BINARY_ARCHIVE_KIND;
+    /** The npm-package provider factory. */
+    readonly npmPackageProvider: typeof import('./providers/npm.js').npmPackageProvider;
+    /** The npm-package item kind. */
+    readonly NPM_PACKAGE_KIND: typeof import('./providers/npm.js').NPM_PACKAGE_KIND;
+    /** The model-cache provider factory. */
+    readonly modelCacheProvider: typeof import('./providers/model.js').modelCacheProvider;
+    /** The model-cache item kind. */
+    readonly MODEL_CACHE_KIND: typeof import('./providers/model.js').MODEL_CACHE_KIND;
+}
+/**
+ * The TYPE half of the v1 `.` surface: every type a caller names when it uses the members above.
+ *
+ * These members exist only at compile time (types are erased), so they are declared as properties of
+ * their own name and never checked against a runtime value. `keyof` them, though, and you have the
+ * type-name list — which is what makes the list data (`TYPE_NAMES_V1`) mechanical rather than a second
+ * hand-kept inventory.
+ *
+ * Most are re-exported from `.` today; `CompatReportWords` and `ServiceContract` are named here because
+ * they appear in public signatures. The snapshot's type list is derived from this interface, so a
+ * member added here and not to the JSON (or the reverse) is a red gate.
+ */
+export interface BaseTypeSurfaceV1 {
+    readonly EnsureOptions: EnsureOptions;
+    readonly InstallContext: InstallContext;
+    readonly InstallManifest: InstallManifest;
+    readonly ItemPolicy: ItemPolicy;
+    readonly Kind: Kind;
+    readonly Manifest: Manifest;
+    readonly MirrorPolicy: MirrorPolicy;
+    readonly OnMissing: OnMissing;
+    readonly Plan: Plan;
+    readonly PlanEntry: PlanEntry;
+    readonly PlanOptions: PlanOptions;
+    readonly ProbeResult: ProbeResult;
+    readonly ProgressEvent: ProgressEvent;
+    readonly PromptFileSpec: PromptFileSpec;
+    readonly LoadedPromptText: LoadedPromptText;
+    readonly PromptFilesIo: PromptFilesIo;
+    readonly PromptFilesLogger: PromptFilesLogger;
+    readonly PromptFilesOptions: PromptFilesOptions;
+    readonly Provider: Provider;
+    readonly ProviderContext: ProviderContext;
+    readonly ProviderPlan: ProviderPlan;
+    readonly ProvisionCode: ProvisionCode;
+    readonly ProvisionEvent: ProvisionEvent;
+    readonly ProvisionFs: ProvisionFs;
+    readonly ProvisionLock: ProvisionLock;
+    readonly ProvisionLogger: ProvisionLogger;
+    readonly ProvisionPolicy: ProvisionPolicy;
+    readonly ProvisionReport: ProvisionReport;
+    readonly ProvisionReportEntry: ProvisionReportEntry;
+    readonly ProvisionStatus: ProvisionStatus;
+    readonly Provisioner: Provisioner;
+    readonly ProvisionerExperimental: ProvisionerExperimental;
+    readonly ProvisionerOptions: ProvisionerOptions;
+    readonly PrunePolicy: PrunePolicy;
+    readonly PruneReport: PruneReport;
+    readonly PublishMeta: PublishMeta;
+    readonly Resolved: Resolved;
+    readonly ResourceHandle: ResourceHandle;
+    readonly ResourceIdentity: ResourceIdentity;
+    readonly ResourceState: ResourceState;
+    readonly Startup: Startup;
+    readonly CompatContext: CompatContext;
+    readonly CompatEvidence: CompatEvidence;
+    readonly CompatLine: CompatLine;
+    readonly CompatLogger: CompatLogger;
+    readonly CompatSpec: CompatSpec;
+    readonly CompatVerdict: CompatVerdict;
+    readonly CompatReportWords: CompatReportWords;
+    readonly ProbeOutcome: ProbeOutcome;
+    readonly ServiceProbe: ServiceProbe;
+    readonly PluginLogger: PluginLogger;
+    readonly PluginLoggerHost: PluginLoggerHost;
+    readonly PluginLoggerOptions: PluginLoggerOptions;
+    readonly StrictCodec: StrictCodec;
+    readonly DataHomeInput: DataHomeInput;
+    readonly InterfaceVerdict: InterfaceVerdict;
+    readonly InterfaceRequirement: InterfaceRequirement;
+}
+/**
+ * Every VALUE name of the v1 `.` surface, in {@link BaseRuntimeV1} declaration order.
+ *
+ * The `satisfies readonly (keyof BaseRuntimeV1)[]` makes a typo or a stale entry a compile error, and
+ * the gate asserts that this list and the module's actual exports are the same set — and that it is
+ * the whole `keyof`, so nothing can live in the interface without also being in the snapshot.
+ */
+export declare const VALUE_NAMES_V1: readonly ["INTERFACE_VERSION", "COMPAT_PREFIX", "BUILD_VERSIONS_FILE", "COMPAT_PROBE_TOOL", "ITEM_SCHEMA_VERSION", "DEFAULT_DEADLINE_MS", "CAPABILITIES", "checkInterface", "readInterfaceRequirement", "provision", "compatReport", "registerMegaphone", "schemaNamesFrom", "verifyRegisteredFaces", "readDeclaredVersions", "readBuildVersions", "readRuntimeVersions", "toolProbeDeclaration", "verdictOf", "floorOf", "resolveRuntimeVersion", "checkServices", "checkInterval", "gatherEvidence", "probeToolsRegistry", "probeTypertRegistry", "declaredSchemaKeys", "PromptFiles", "createPluginLogger", "familyHome", "familyToolsDir", "familyModelsDir", "resolveDataHome", "expandHome", "strictCodec", "endpointId", "fieldSymbol", "resultSymbol", "createProvisioner", "normalizeOnMissing", "ProvisionError", "reasonOf", "binaryArchiveProvider", "BINARY_ARCHIVE_KIND", "npmPackageProvider", "NPM_PACKAGE_KIND", "modelCacheProvider", "MODEL_CACHE_KIND"];
+/**
+ * Every TYPE name of the v1 `.` surface, in {@link BaseTypeSurfaceV1} declaration order.
+ *
+ * Types are erased, so this is the only form in which they can be enumerated at runtime. The
+ * `satisfies` clause keeps it honest against the interface, and the gate asserts the two together are
+ * exactly the interface's members.
+ */
+export declare const TYPE_NAMES_V1: readonly ["EnsureOptions", "InstallContext", "InstallManifest", "ItemPolicy", "Kind", "Manifest", "MirrorPolicy", "OnMissing", "Plan", "PlanEntry", "PlanOptions", "ProbeResult", "ProgressEvent", "PromptFileSpec", "LoadedPromptText", "PromptFilesIo", "PromptFilesLogger", "PromptFilesOptions", "Provider", "ProviderContext", "ProviderPlan", "ProvisionCode", "ProvisionEvent", "ProvisionFs", "ProvisionLock", "ProvisionLogger", "ProvisionPolicy", "ProvisionReport", "ProvisionReportEntry", "ProvisionStatus", "Provisioner", "ProvisionerExperimental", "ProvisionerOptions", "PrunePolicy", "PruneReport", "PublishMeta", "Resolved", "ResourceHandle", "ResourceIdentity", "ResourceState", "Startup", "CompatContext", "CompatEvidence", "CompatLine", "CompatLogger", "CompatSpec", "CompatVerdict", "CompatReportWords", "ProbeOutcome", "ServiceProbe", "PluginLogger", "PluginLoggerHost", "PluginLoggerOptions", "StrictCodec", "DataHomeInput", "InterfaceVerdict", "InterfaceRequirement"];
+//# sourceMappingURL=interface.d.ts.map

package/dist/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../src/interface.ts"],"names":[],"mappings":"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"}

package/dist/interface.js

@@ -0,0 +1,136 @@
+/**
+ * The integer interface generation this module implements.
+ *
+ * `1` is the first frozen generation: the surface recorded by `api/interface-v1.json`. The file name's
+ * `N` and this constant are the SAME fact — `test/public-surface.spec.ts` asserts that the snapshot for
+ * this constant exists and that its `interfaceVersion` field equals it, so "the JSON says v2, the
+ * constant says 1" cannot happen. Bump it (and add `api/interface-vN.json`) only for an interface
+ * change (INTERFACE.md §1); a behaviour change or a fix does NOT touch it. The plugins bake this number
+ * into their artifacts and compare it, at startup, with the number the base they loaded reports — a
+ * difference is a warning and a capability-level degradation, never a refused mount.
+ */
+export const INTERFACE_VERSION = 1;
+/**
+ * Every VALUE name of the v1 `.` surface, in {@link BaseRuntimeV1} declaration order.
+ *
+ * The `satisfies readonly (keyof BaseRuntimeV1)[]` makes a typo or a stale entry a compile error, and
+ * the gate asserts that this list and the module's actual exports are the same set — and that it is
+ * the whole `keyof`, so nothing can live in the interface without also being in the snapshot.
+ */
+export const VALUE_NAMES_V1 = [
+    'INTERFACE_VERSION',
+    'COMPAT_PREFIX',
+    'BUILD_VERSIONS_FILE',
+    'COMPAT_PROBE_TOOL',
+    'ITEM_SCHEMA_VERSION',
+    'DEFAULT_DEADLINE_MS',
+    'CAPABILITIES',
+    'checkInterface',
+    'readInterfaceRequirement',
+    'provision',
+    'compatReport',
+    'registerMegaphone',
+    'schemaNamesFrom',
+    'verifyRegisteredFaces',
+    'readDeclaredVersions',
+    'readBuildVersions',
+    'readRuntimeVersions',
+    'toolProbeDeclaration',
+    'verdictOf',
+    'floorOf',
+    'resolveRuntimeVersion',
+    'checkServices',
+    'checkInterval',
+    'gatherEvidence',
+    'probeToolsRegistry',
+    'probeTypertRegistry',
+    'declaredSchemaKeys',
+    'PromptFiles',
+    'createPluginLogger',
+    'familyHome',
+    'familyToolsDir',
+    'familyModelsDir',
+    'resolveDataHome',
+    'expandHome',
+    'strictCodec',
+    'endpointId',
+    'fieldSymbol',
+    'resultSymbol',
+    'createProvisioner',
+    'normalizeOnMissing',
+    'ProvisionError',
+    'reasonOf',
+    'binaryArchiveProvider',
+    'BINARY_ARCHIVE_KIND',
+    'npmPackageProvider',
+    'NPM_PACKAGE_KIND',
+    'modelCacheProvider',
+    'MODEL_CACHE_KIND',
+];
+/**
+ * Every TYPE name of the v1 `.` surface, in {@link BaseTypeSurfaceV1} declaration order.
+ *
+ * Types are erased, so this is the only form in which they can be enumerated at runtime. The
+ * `satisfies` clause keeps it honest against the interface, and the gate asserts the two together are
+ * exactly the interface's members.
+ */
+export const TYPE_NAMES_V1 = [
+    'EnsureOptions',
+    'InstallContext',
+    'InstallManifest',
+    'ItemPolicy',
+    'Kind',
+    'Manifest',
+    'MirrorPolicy',
+    'OnMissing',
+    'Plan',
+    'PlanEntry',
+    'PlanOptions',
+    'ProbeResult',
+    'ProgressEvent',
+    'PromptFileSpec',
+    'LoadedPromptText',
+    'PromptFilesIo',
+    'PromptFilesLogger',
+    'PromptFilesOptions',
+    'Provider',
+    'ProviderContext',
+    'ProviderPlan',
+    'ProvisionCode',
+    'ProvisionEvent',
+    'ProvisionFs',
+    'ProvisionLock',
+    'ProvisionLogger',
+    'ProvisionPolicy',
+    'ProvisionReport',
+    'ProvisionReportEntry',
+    'ProvisionStatus',
+    'Provisioner',
+    'ProvisionerExperimental',
+    'ProvisionerOptions',
+    'PrunePolicy',
+    'PruneReport',
+    'PublishMeta',
+    'Resolved',
+    'ResourceHandle',
+    'ResourceIdentity',
+    'ResourceState',
+    'Startup',
+    'CompatContext',
+    'CompatEvidence',
+    'CompatLine',
+    'CompatLogger',
+    'CompatSpec',
+    'CompatVerdict',
+    'CompatReportWords',
+    'ProbeOutcome',
+    'ServiceProbe',
+    'PluginLogger',
+    'PluginLoggerHost',
+    'PluginLoggerOptions',
+    'StrictCodec',
+    'DataHomeInput',
+    'InterfaceVerdict',
+    'InterfaceRequirement',
+];
+//# sourceMappingURL=interface.js.map

package/dist/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../src/interface.ts"],"names":[],"mappings":"AA6EA;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAA;AA8MlC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,mBAAmB;IACnB,eAAe;IACf,qBAAqB;IACrB,mBAAmB;IACnB,qBAAqB;IACrB,qBAAqB;IACrB,cAAc;IACd,gBAAgB;IAChB,0BAA0B;IAC1B,WAAW;IACX,cAAc;IACd,mBAAmB;IACnB,iBAAiB;IACjB,uBAAuB;IACvB,sBAAsB;IACtB,mBAAmB;IACnB,qBAAqB;IACrB,sBAAsB;IACtB,WAAW;IACX,SAAS;IACT,uBAAuB;IACvB,eAAe;IACf,eAAe;IACf,gBAAgB;IAChB,oBAAoB;IACpB,qBAAqB;IACrB,oBAAoB;IACpB,aAAa;IACb,oBAAoB;IACpB,YAAY;IACZ,gBAAgB;IAChB,iBAAiB;IACjB,iBAAiB;IACjB,YAAY;IACZ,aAAa;IACb,YAAY;IACZ,aAAa;IACb,cAAc;IACd,mBAAmB;IACnB,oBAAoB;IACpB,gBAAgB;IAChB,UAAU;IACV,uBAAuB;IACvB,qBAAqB;IACrB,oBAAoB;IACpB,kBAAkB;IAClB,oBAAoB;IACpB,kBAAkB;CACiC,CAAA;AAErD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,eAAe;IACf,gBAAgB;IAChB,iBAAiB;IACjB,YAAY;IACZ,MAAM;IACN,UAAU;IACV,cAAc;IACd,WAAW;IACX,MAAM;IACN,WAAW;IACX,aAAa;IACb,aAAa;IACb,eAAe;IACf,gBAAgB;IAChB,kBAAkB;IAClB,eAAe;IACf,mBAAmB;IACnB,oBAAoB;IACpB,UAAU;IACV,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,gBAAgB;IAChB,aAAa;IACb,eAAe;IACf,iBAAiB;IACjB,iBAAiB;IACjB,iBAAiB;IACjB,sBAAsB;IACtB,iBAAiB;IACjB,aAAa;IACb,yBAAyB;IACzB,oBAAoB;IACpB,aAAa;IACb,aAAa;IACb,aAAa;IACb,UAAU;IACV,gBAAgB;IAChB,kBAAkB;IAClB,eAAe;IACf,SAAS;IACT,eAAe;IACf,gBAAgB;IAChB,YAAY;IACZ,cAAc;IACd,YAAY;IACZ,eAAe;IACf,mBAAmB;IACnB,cAAc;IACd,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,qBAAqB;IACrB,aAAa;IACb,eAAe;IACf,kBAAkB;IAClB,sBAAsB;CACiC,CAAA"}

package/dist/interface_gate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The interface generation a plugin artifact was baked for — the base's side of the contract.
+ *
+ * `scripts/lib/interface-version.mjs` writes it beside the built entry; the base reads it back here
+ * so both plugins share ONE reader (and ONE definition of "malformed", which is `undefined`).
+ */
+export interface InterfaceRequirement {
+    /** The base package version the bake was taken from, so a diagnostic can name it. */
+    readonly baseVersion: string;
+    /** The `INTERFACE_VERSION` of the base the artifact was built against. */
+    readonly interfaceVersion: number;
+}
+/**
+ * What {@link checkInterface} decided.
+ *
+ * `ok` — both sides were readable and name the same generation; use the base normally.
+ * `incompatible` — both sides were readable and differ (either direction); a caller must NOT use the
+ * base's shared capabilities. The family invariant still holds: this is a degradation, never a
+ * refused mount.
+ * `cannot-tell` — at least one side could not be read. "Cannot tell" is never "incompatible": the
+ * caller warns and uses the base normally.
+ */
+export interface InterfaceVerdict {
+    readonly status: 'ok' | 'incompatible' | 'cannot-tell';
+    /** The generation the caller was built for, when it was readable. */
+    readonly required?: number;
+    /** The generation the loaded module reported, when it was readable. */
+    readonly loaded?: number;
+    /**
+     * One sentence a caller can log verbatim — present whenever the status is not `ok`, and absent when
+     * it is. The caller owns the wording around it (prefix, "mounting anyway", …).
+     */
+    readonly reason?: string;
+}
+/**
+ * Compare the interface generation a caller requires with the one a loaded module reports.
+ *
+ * Pure, bidirectional and total: it reads exactly one property, guards that read, and answers a
+ * verdict for every input. Both arguments are trusted only as far as they can be read.
+ *
+ * @param required - the generation the caller was built for (its baked `interfaceVersion`).
+ * @param module - the loaded base module; only `INTERFACE_VERSION` is read.
+ * @returns the verdict; `status` is `cannot-tell` for any side that could not be read.
+ */
+export declare function checkInterface(required: number, module: {
+    readonly INTERFACE_VERSION?: unknown;
+}): InterfaceVerdict;
+/**
+ * Read the interface requirement a plugin artifact was baked with.
+ *
+ * A missing, unreadable or malformed file is `undefined` — "not baked" — never a throw: every caller
+ * is a startup path that must degrade to a warning, and a half-written record must not read as a
+ * version. This is the reader the PLUGINS use on their startup path; the build-side link step reads
+ * the same file with its own copy in `scripts/lib/interface-version.mjs` (it runs before the base it
+ * is about to vendor is importable), and the two field names are the same fact.
+ *
+ * @param url - the record's location, normally `new URL('./interface-version.json', import.meta.url)`.
+ * @returns `{ baseVersion, interfaceVersion }`, or `undefined`.
+ */
+export declare function readInterfaceRequirement(url: URL | string): InterfaceRequirement | undefined;
+//# sourceMappingURL=interface_gate.d.ts.map

package/dist/interface_gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface_gate.d.ts","sourceRoot":"","sources":["../src/interface_gate.ts"],"names":[],"mappings":"AA4BA;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,qFAAqF;IACrF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAClC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,cAAc,GAAG,aAAa,CAAA;IACtD,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IAAE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C,gBAAgB,CAiClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAa5F"}

package/dist/interface_gate.js

@@ -0,0 +1,103 @@
+/**
+ * The RUNTIME interface gate — the decision half of the family's compatibility contract.
+ *
+ * `INTERFACE_VERSION` (see {@link INTERFACE_VERSION} in `./interface.js`) is the generation number of
+ * the `.` surface; the plugins BAKE the generation they were built for into their artifact
+ * (`lib/interface-version.json`, written by each tree's `scripts/link-envinit.mjs`) and, at startup,
+ * compare it with the number the base they actually loaded reports. This module is that comparison.
+ *
+ * It lives in the BASE, not in each plugin, for the same reason the rest of the shared kit does
+ * (root `AGENTS.md`: "can this knowledge be fixed by one base release?"): the verdict semantics are
+ * now the family's MAIN contract, so a wrong direction, an unguarded property read or a thrown error
+ * must be fixable with one base release, not two plugin rebuilds. The plugins keep only the
+ * consumption: read their own bake through {@link readInterfaceRequirement}, call
+ * {@link checkInterface}, and act on the verdict.
+ *
+ * Two properties are absolute, and both are why this is a pure function rather than a live check:
+ *
+ *  - **It never throws.** A gate that throws while deciding would reject a mount it is not allowed to
+ *    reject. A module whose property access throws (the "hostile module" the plugins' loaders are
+ *    built to survive) reads as "reports no INTERFACE_VERSION", i.e. `cannot-tell`.
+ *  - **It is bidirectional.** A plugin written for a NEWER generation than the base it loaded is as
+ *    incompatible as one written for an older one; "in range but another generation" is the one case
+ *    `supportedRange` cannot see, so this gate must see it in both directions.
+ *
+ * @module @avantf/dsh-plugin-base/interface_gate
+ */
+import { readFileSync } from 'node:fs';
+/**
+ * Compare the interface generation a caller requires with the one a loaded module reports.
+ *
+ * Pure, bidirectional and total: it reads exactly one property, guards that read, and answers a
+ * verdict for every input. Both arguments are trusted only as far as they can be read.
+ *
+ * @param required - the generation the caller was built for (its baked `interfaceVersion`).
+ * @param module - the loaded base module; only `INTERFACE_VERSION` is read.
+ * @returns the verdict; `status` is `cannot-tell` for any side that could not be read.
+ */
+export function checkInterface(required, module) {
+    // Guarded read: a module that throws on property access is "reports no INTERFACE_VERSION", not a
+    // failure of the gate (and never a rejected mount).
+    let loaded;
+    try {
+        loaded = module.INTERFACE_VERSION;
+    }
+    catch {
+        loaded = undefined;
+    }
+    const loadedVersion = typeof loaded === 'number' && Number.isInteger(loaded) && loaded > 0 ? loaded : undefined;
+    if (!Number.isInteger(required) || required <= 0) {
+        return {
+            status: 'cannot-tell',
+            ...(loadedVersion === undefined ? {} : { loaded: loadedVersion }),
+            reason: `this build has no usable baked interface generation (got ${JSON.stringify(required)}); the runtime interface gate cannot run`,
+        };
+    }
+    if (loadedVersion === undefined) {
+        return {
+            status: 'cannot-tell',
+            required,
+            reason: 'the loaded base reports no INTERFACE_VERSION; which interface generation it implements cannot be told',
+        };
+    }
+    if (loadedVersion === required)
+        return { status: 'ok', required, loaded: loadedVersion };
+    return {
+        status: 'incompatible',
+        required,
+        loaded: loadedVersion,
+        reason: `this build was written for interface generation ${String(required)} but the loaded base reports ${String(loadedVersion)}`
+            + ` (${loadedVersion > required ? 'newer' : 'older'} generation); the base's shared capabilities are not used`,
+    };
+}
+/**
+ * Read the interface requirement a plugin artifact was baked with.
+ *
+ * A missing, unreadable or malformed file is `undefined` — "not baked" — never a throw: every caller
+ * is a startup path that must degrade to a warning, and a half-written record must not read as a
+ * version. This is the reader the PLUGINS use on their startup path; the build-side link step reads
+ * the same file with its own copy in `scripts/lib/interface-version.mjs` (it runs before the base it
+ * is about to vendor is importable), and the two field names are the same fact.
+ *
+ * @param url - the record's location, normally `new URL('./interface-version.json', import.meta.url)`.
+ * @returns `{ baseVersion, interfaceVersion }`, or `undefined`.
+ */
+export function readInterfaceRequirement(url) {
+    try {
+        const parsed = JSON.parse(readFileSync(url, 'utf8'));
+        if (typeof parsed !== 'object' || parsed === null)
+            return undefined;
+        const record = parsed;
+        const baseVersion = record['baseVersion'];
+        const interfaceVersion = record['interfaceVersion'];
+        if (typeof baseVersion !== 'string' || baseVersion === '')
+            return undefined;
+        if (typeof interfaceVersion !== 'number' || !Number.isInteger(interfaceVersion) || interfaceVersion <= 0)
+            return undefined;
+        return { baseVersion, interfaceVersion };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=interface_gate.js.map

package/dist/interface_gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface_gate.js","sourceRoot":"","sources":["../src/interface_gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAsCtC;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,MAAgD;IAEhD,iGAAiG;IACjG,oDAAoD;IACpD,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,CAAC,iBAAiB,CAAA;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,GAAG,SAAS,CAAA;IACpB,CAAC;IACD,MAAM,aAAa,GAAG,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;IAE/G,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,GAAG,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;YACjE,MAAM,EAAE,4DAA4D,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,0CAA0C;SACvI,CAAA;IACH,CAAC;IACD,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO;YACL,MAAM,EAAE,aAAa;YACrB,QAAQ;YACR,MAAM,EAAE,uGAAuG;SAChH,CAAA;IACH,CAAC;IACD,IAAI,aAAa,KAAK,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,CAAA;IACxF,OAAO;QACL,MAAM,EAAE,cAAc;QACtB,QAAQ;QACR,MAAM,EAAE,aAAa;QACrB,MAAM,EAAE,mDAAmD,MAAM,CAAC,QAAQ,CAAC,gCAAgC,MAAM,CAAC,aAAa,CAAC,EAAE;cAC9H,KAAK,aAAa,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,2DAA2D;KACjH,CAAA;AACH,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAiB;IACxD,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAA;QAC7D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,SAAS,CAAA;QACnE,MAAM,MAAM,GAAG,MAAiC,CAAA;QAChD,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAA;QACzC,MAAM,gBAAgB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAA;QACnD,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,EAAE;YAAE,OAAO,SAAS,CAAA;QAC3E,IAAI,OAAO,gBAAgB,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,IAAI,gBAAgB,IAAI,CAAC;YAAE,OAAO,SAAS,CAAA;QAC1H,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAA;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC"}

package/dist/internal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Framework building blocks shared by the core and the entry points.
+ * @module internal
+ */
+export { defaultFs, exists, linkOrCopy } from './fs.js';
+export { defaultLock, pidIsAlive } from './lock.js';
+export { extractTarGz, safeEntryPath } from './tar.js';
+export { extractZip } from './zip.js';
+export type { ZipExtractOptions } from './zip.js';
+export { assertRange, compareVersions, parseRange, parseVersion, satisfies, satisfiesRange, selectVersion } from './semver.js';
+export type { Range, Version } from './semver.js';
+export { INSTALL_MANIFEST_FILE, MANIFEST_SCHEMA_VERSION, aliasLegacyManifest, decodeJson, encodeInstallManifest, readInstallManifest, } from './manifest.js';
+export { assertPackageName } from './package-name.js';
+export { sriOfSha256, verifyIntegrity } from './integrity.js';
+export { LAYOUT_SCHEMA_VERSION, STATUS_SCHEMA_VERSION, mergeRows, persistStatus, readDeclared, readLayout, readStatus, recordDeclared, writeLayout, } from './state.js';
+export type { DeclaredEntry, DeclaredFile, LayoutFile, StatusFile, StatusRow } from './state.js';
+export { BUILTIN_KINDS, IMPLEMENTED_POLICY_KEYS, ITEM_FIELDS, MANIFEST_FIELDS, UNIMPLEMENTED_POLICY_KEYS, UNIMPLEMENTED_PROVISION_POLICY_KEYS, hasStarBranch, isNamespacedKind, lintManifest, lintManifestText, unknownFields, } from './lint.js';
+export type { LintFinding, LintResult } from './lint.js';
+export { candidateUrls, downloadBytes, fetchImplOf, platformKey, readCapped, signalFor, verifySha256, DEFAULT_MAX_BYTES } from './net.js';
+export { CONTROL_DIR, assertSafeRelativePath, assertSafeRelativeRoot, controlRoot, declaredPath, layoutPath, lockPath, quarantineRoot, stagingDir, statusLockPath, statusPath, tempRoot, versionSegment, } from './layout.js';
+export { BOOTSTRAP_SUBPATH, FRAMEWORK_INLINING_BEACONS, FRAMEWORK_PACKAGE, MIN_INLINING_BEACONS, findFrameworkImports, findInliningBeacons, isBootstrapSpecifier, } from './artifact.js';
+export type { FrameworkImportKind, FrameworkImportRef } from './artifact.js';
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACrC,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC9H,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,EACL,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,UAAU,EACV,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,UAAU,EACV,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAChG,OAAO,EACL,aAAa,EACb,uBAAuB,EACvB,WAAW,EACX,eAAe,EACf,yBAAyB,EACzB,mCAAmC,EACnC,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,aAAa,GACd,MAAM,WAAW,CAAA;AAClB,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACzI,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,sBAAsB,EACtB,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EACR,cAAc,EACd,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,cAAc,GACf,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA"}