@deftai/directive-types 0.68.0 → 0.69.0

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { collectExtensionProperties, type ExtensionKey, isExtensionKey, } from "
 export { GATE_EXIT_CONFIG_ERROR, GATE_EXIT_OK, GATE_EXIT_VIOLATION, type GateExitCode, type GateResult, } from "./gate.js";
 export { type PlanPolicy, type ProjectionProviderExpectation, type ProjectionProviderPolicy, REGISTERED_POLICY_FIELD_NAMES, type TriageScopeRule, } from "./policy.js";
 export { isVBriefReferenceType, KNOWN_REFERENCE_TYPES, type KnownReferenceType, referenceTypeMatches, type TrustLevel, type VBriefReference, } from "./reference.js";
+export { RESOLUTION_ENCODINGS, RESOLUTION_MODES, RESOLUTION_PLAN_SCHEMA_VERSION, type ResolutionEncoding, type ResolutionFacts, type ResolutionFile, type ResolutionMode, type ResolutionNextAction, type ResolutionPlan, } from "./resolution.js";
 export { FOLDER_ALLOWED_STATUSES, type Status, VALID_STATUSES, } from "./status.js";
 /** Relative path to the published v0.6 core JSON Schema inside the npm package. */
 export declare const PUBLISHED_VBRIEF_CORE_SCHEMA_PATH: "schemas/vbrief-core-0.6.schema.json";

package/dist/index.js

@@ -3,6 +3,7 @@ export { collectExtensionProperties, isExtensionKey, } from "./extension.js";
 export { GATE_EXIT_CONFIG_ERROR, GATE_EXIT_OK, GATE_EXIT_VIOLATION, } from "./gate.js";
 export { REGISTERED_POLICY_FIELD_NAMES, } from "./policy.js";
 export { isVBriefReferenceType, KNOWN_REFERENCE_TYPES, referenceTypeMatches, } from "./reference.js";
+export { RESOLUTION_ENCODINGS, RESOLUTION_MODES, RESOLUTION_PLAN_SCHEMA_VERSION, } from "./resolution.js";
 export { FOLDER_ALLOWED_STATUSES, VALID_STATUSES, } from "./status.js";
 /** Relative path to the published v0.6 core JSON Schema inside the npm package. */
 export const PUBLISHED_VBRIEF_CORE_SCHEMA_PATH = "schemas/vbrief-core-0.6.schema.json";

package/dist/policy.d.ts

@@ -10,6 +10,14 @@ export interface PlanPolicy {
     readonly allowDirectCommitsToMaster?: boolean;
     readonly wipCap?: number;
     readonly sessionRitualStalenessHours?: number | null;
+    /**
+     * Engine-vs-pin skew tolerance for the three-band skew policy (#2264).
+     *
+     * Pre-1.0 the window is measured in minor versions (default 3); post-1.0 it
+     * collapses to "same major". `engine > pin` beyond this window fails closed
+     * unless `--accept-engine-jump` / `DEFT_ACCEPT_ENGINE_SKEW=1` is supplied.
+     */
+    readonly engineSkewWindow?: number | null;
     readonly triageScope?: readonly TriageScopeRule[];
     readonly triageScopeIgnores?: readonly unknown[];
     readonly triageRankingLabels?: readonly string[];
@@ -32,5 +40,5 @@ export interface ProjectionProviderPolicy {
     readonly [key: `x-${string}`]: unknown;
 }
 /** Canonical dotted policy field names registered by the directive engine. */
-export declare const REGISTERED_POLICY_FIELD_NAMES: readonly ["plan.policy.allowDirectCommitsToMaster", "plan.policy.wipCap", "plan.policy.sessionRitualStalenessHours", "plan.policy.triageScope", "plan.policy.triageScopeIgnores", "plan.policy.triageRankingLabels", "plan.policy.triageAutoClassify", "plan.policy.triageHoldMarkers", "plan.policy.swarmSubagentBackend"];
+export declare const REGISTERED_POLICY_FIELD_NAMES: readonly ["plan.policy.allowDirectCommitsToMaster", "plan.policy.wipCap", "plan.policy.sessionRitualStalenessHours", "plan.policy.triageScope", "plan.policy.triageScopeIgnores", "plan.policy.triageRankingLabels", "plan.policy.triageAutoClassify", "plan.policy.triageHoldMarkers", "plan.policy.swarmSubagentBackend", "plan.policy.engineSkewWindow"];
 //# sourceMappingURL=policy.d.ts.map

package/dist/policy.js

@@ -9,5 +9,6 @@ export const REGISTERED_POLICY_FIELD_NAMES = [
     "plan.policy.triageAutoClassify",
     "plan.policy.triageHoldMarkers",
     "plan.policy.swarmSubagentBackend",
+    "plan.policy.engineSkewWindow",
 ];
 //# sourceMappingURL=policy.js.map

package/dist/resolution.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Public contract for the shared resolution spine (keystone #2264 / epic #2203).
+ *
+ * `classify()` (in @deftai/directive-core/resolution) produces the orthogonal
+ * {@link ResolutionFacts} fact-set; `plan()` applies one ordered precedence
+ * table over those facts and emits a {@link ResolutionPlan}, the single
+ * versioned public JSON schema every epic-#2203 consumer derives from
+ * (init / update / doctor / headless). Keeping the decision behind one schema
+ * closes the #537 split-source drift risk.
+ *
+ * The matching JSON Schema lives at
+ * `packages/types/schemas/resolution-plan-v1.schema.json` and MUST stay in
+ * lockstep with the types below (a lockstep test enforces it in the core
+ * resolution suite).
+ */
+/** Schema version tag stamped into every {@link ResolutionPlan}. */
+export declare const RESOLUTION_PLAN_SCHEMA_VERSION: "resolution-plan/v1";
+/** Content encoding for a file the plan recommends materialising. */
+export type ResolutionEncoding = "utf-8" | "base64";
+/**
+ * Orthogonal project + engine fact-set returned by `classify()`.
+ *
+ * It is deliberately a flat set of independent facts, never a single collapsed
+ * enum — `plan()` owns the collapse into one recommended action so there is
+ * exactly one precedence table in the system.
+ */
+export interface ResolutionFacts {
+    /** A git worktree is present at the classified root. */
+    readonly hasGit: boolean;
+    /** Consumer application source is present (app markers, not just a Deft deposit). */
+    readonly hasAppCode: boolean;
+    /** The canonical `.deft/core/` vendored payload directory is present. */
+    readonly hasDeftCore: boolean;
+    /** Version marker read from the `.deft/core/VERSION` manifest, or null. */
+    readonly deftCorePayloadVersion: string | null;
+    /** `AGENTS.md` carries a v2/v3 managed section. */
+    readonly hasManagedSection: boolean;
+    /** `sha=` attribute parsed from the managed-section open marker, or null. */
+    readonly managedSectionSha: string | null;
+    /** A legacy `vbrief/` lifecycle tree is present. */
+    readonly hasVbrief: boolean;
+    /** An `xbrief/` lifecycle tree is present. */
+    readonly hasXbrief: boolean;
+    /** Pre-v0.20 document-model artifacts require migration before any gate. */
+    readonly preCutoverArtifacts: boolean;
+    /** A Directive engine is reachable in the execution environment. */
+    readonly engineReachable: boolean;
+    /** Version of the reachable engine, or null when unreachable. */
+    readonly engineVersion: string | null;
+    /** Exact committed `package.json` devDependency pin, or null. */
+    readonly pinVersion: string | null;
+}
+/** A file the plan recommends materialising (empty in the keystone spine). */
+export interface ResolutionFile {
+    readonly path: string;
+    readonly content: string;
+    readonly encoding: ResolutionEncoding;
+}
+/** The single recommended next action for the resolved mode. */
+export interface ResolutionNextAction {
+    /** Command to run, or null when the action is manual / has no single command. */
+    readonly command: string | null;
+    /** Why this action is recommended (the resolved fact combination). */
+    readonly rootCause: string;
+    /** Human-facing remediation guidance. */
+    readonly remediation: string;
+}
+/**
+ * The one recommended resolution mode. `plan()` emits exactly one.
+ *
+ * - `proceed`         — engine + content matched; run the requested gate.
+ * - `init`            — no usable deposit; deposit / reconstitute one.
+ * - `migrate`         — pre-v0.20 (or legacy) artifacts must migrate first.
+ * - `update`          — deposit present but content behind the pin; forward-migrate.
+ * - `install-global`  — install the pinned engine into the global prefix.
+ * - `install-sandbox` — install the pinned engine into `.deft/.cli/<platform>`.
+ * - `install-staged`  — registry down; install from a staged / vendored payload.
+ * - `blocked`         — cannot self-heal (skew fail-closed, no payload); needs an operator.
+ */
+export type ResolutionMode = "proceed" | "init" | "migrate" | "update" | "install-global" | "install-sandbox" | "install-staged" | "blocked";
+/** The versioned public output of `plan()` — the single source of truth. */
+export interface ResolutionPlan {
+    readonly schemaVersion: typeof RESOLUTION_PLAN_SCHEMA_VERSION;
+    readonly mode: ResolutionMode;
+    readonly files: readonly ResolutionFile[];
+    readonly nextAction: ResolutionNextAction;
+    readonly warnings: readonly string[];
+}
+/** All resolution modes, exported for exhaustiveness checks + schema lockstep. */
+export declare const RESOLUTION_MODES: readonly ResolutionMode[];
+/** All resolution encodings, exported for schema lockstep. */
+export declare const RESOLUTION_ENCODINGS: readonly ResolutionEncoding[];
+//# sourceMappingURL=resolution.d.ts.map

package/dist/resolution.js

@@ -0,0 +1,31 @@
+/**
+ * Public contract for the shared resolution spine (keystone #2264 / epic #2203).
+ *
+ * `classify()` (in @deftai/directive-core/resolution) produces the orthogonal
+ * {@link ResolutionFacts} fact-set; `plan()` applies one ordered precedence
+ * table over those facts and emits a {@link ResolutionPlan}, the single
+ * versioned public JSON schema every epic-#2203 consumer derives from
+ * (init / update / doctor / headless). Keeping the decision behind one schema
+ * closes the #537 split-source drift risk.
+ *
+ * The matching JSON Schema lives at
+ * `packages/types/schemas/resolution-plan-v1.schema.json` and MUST stay in
+ * lockstep with the types below (a lockstep test enforces it in the core
+ * resolution suite).
+ */
+/** Schema version tag stamped into every {@link ResolutionPlan}. */
+export const RESOLUTION_PLAN_SCHEMA_VERSION = "resolution-plan/v1";
+/** All resolution modes, exported for exhaustiveness checks + schema lockstep. */
+export const RESOLUTION_MODES = [
+    "proceed",
+    "init",
+    "migrate",
+    "update",
+    "install-global",
+    "install-sandbox",
+    "install-staged",
+    "blocked",
+];
+/** All resolution encodings, exported for schema lockstep. */
+export const RESOLUTION_ENCODINGS = ["utf-8", "base64"];
+//# sourceMappingURL=resolution.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-types",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Shared TypeScript types for the Directive framework engine.",
   "type": "module",
   "main": "./dist/index.js",

package/schemas/resolution-plan-v1.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xbrief.dev/schemas/resolution-plan-v1.schema.json",
+  "title": "Resolution Plan Schema v1",
+  "description": "Versioned public output of the resolution-spine plan() function (keystone #2264 / epic #2203). The single source of truth every consumption context (init / update / doctor / headless) derives from. MUST stay in lockstep with @deftai/directive-types resolution.ts.",
+  "type": "object",
+  "required": ["schemaVersion", "mode", "files", "nextAction", "warnings"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "resolution-plan/v1",
+      "description": "Schema version tag stamped into every plan."
+    },
+    "mode": {
+      "$ref": "#/$defs/ResolutionMode"
+    },
+    "files": {
+      "type": "array",
+      "description": "Files the plan recommends materialising (empty in the keystone spine).",
+      "items": { "$ref": "#/$defs/ResolutionFile" }
+    },
+    "nextAction": {
+      "$ref": "#/$defs/ResolutionNextAction"
+    },
+    "warnings": {
+      "type": "array",
+      "description": "Non-fatal advisories (loud skew deltas, legacy-tree hints, reconciliation mismatches).",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "ResolutionMode": {
+      "type": "string",
+      "description": "The one recommended resolution mode. plan() emits exactly one.",
+      "enum": [
+        "proceed",
+        "init",
+        "migrate",
+        "update",
+        "install-global",
+        "install-sandbox",
+        "install-staged",
+        "blocked"
+      ]
+    },
+    "ResolutionEncoding": {
+      "type": "string",
+      "enum": ["utf-8", "base64"]
+    },
+    "ResolutionFile": {
+      "type": "object",
+      "required": ["path", "content", "encoding"],
+      "additionalProperties": false,
+      "properties": {
+        "path": { "type": "string" },
+        "content": { "type": "string" },
+        "encoding": { "$ref": "#/$defs/ResolutionEncoding" }
+      }
+    },
+    "ResolutionNextAction": {
+      "type": "object",
+      "required": ["command", "rootCause", "remediation"],
+      "additionalProperties": false,
+      "properties": {
+        "command": {
+          "type": ["string", "null"],
+          "description": "Command to run, or null when the action is manual / has no single command."
+        },
+        "rootCause": { "type": "string" },
+        "remediation": { "type": "string" }
+      }
+    }
+  }
+}