@karmaniverous/stan-core 0.5.0 → 0.6.0

package/dist/types/index.d.ts

@@ -1,3 +1,77 @@
+import { z } from 'zod';
+
+/**
+ * Defines deterministic selection report types for archive/diff operations and
+ * a safe surfacing helper; no filesystem IO; used by adapters for reporting.
+ * @module
+ */
+/**
+ * Selection counts for a single archive/diff/meta operation.
+ *
+ * Meanings:
+ * - candidates: initial input set size for the operation (e.g. listFiles() size,
+ *   or allowlist length as provided by the caller).
+ * - selected: pre-classifier selected set size (e.g. after filterFiles(), or
+ *   the de-duped allowlist).
+ * - archived: post-classifier list size passed to tar.create().
+ * - excludedBinaries: count excluded by classifier (binary detection).
+ * - largeText: count flagged by classifier (included, but warned).
+ */
+type SelectionReportCounts = {
+    candidates: number;
+    selected: number;
+    archived: number;
+    excludedBinaries: number;
+    largeText: number;
+};
+/**
+ * Deterministic, presentation-free selection report surfaced via callback.
+ *
+ * Notes:
+ * - `outputFile` is an absolute path.
+ * - `hasWarnings` is derived from classifier counts (binaries excluded and/or
+ *   large text flagged), not from any warnings string.
+ */
+type SelectionReport = {
+    kind: 'archive';
+    mode: 'denylist' | 'allowlist';
+    stanPath: string;
+    outputFile: string;
+    includeOutputDir: boolean;
+    hasWarnings: boolean;
+    counts: SelectionReportCounts;
+} | {
+    kind: 'diff';
+    mode: 'denylist' | 'allowlist';
+    stanPath: string;
+    outputFile: string;
+    includeOutputDirInDiff: boolean;
+    updateSnapshot: 'never' | 'createIfMissing' | 'replace';
+    snapshotExists: boolean;
+    /**
+     * Size of the base selection set from which changes were computed
+     * (e.g. filtered selection or allowlist after de-dupe).
+     */
+    baseSelected: number;
+    sentinelUsed: boolean;
+    hasWarnings: boolean;
+    counts: SelectionReportCounts;
+} | {
+    kind: 'meta';
+    mode: 'allowlist';
+    stanPath: string;
+    outputFile: string;
+    hasWarnings: false;
+    counts: SelectionReportCounts;
+};
+
+/**
+ * Creates full archives (`archive.tar`) from selected repo files; excludes
+ * binaries, surfaces warnings via callback, and maintains `archive.prev.tar`;
+ * performs filesystem IO; no console output.
+ * @module
+ */
+
 /** Options to control archive creation. */
 type CreateArchiveOptions = {
     /** When true, include the `stanPath/output` directory inside the archive. */
@@ -7,34 +81,17 @@ type CreateArchiveOptions = {
      * Written to `stanPath/output/<fileName>`.
      */
     fileName?: string;
-    /** Allow‑list globs; when provided, overrides excludes. */
+    /** Additive allow‑list globs (can re-include gitignored files); excludes and reserved denials still win. */
     includes?: string[];
     /**
-     * Deny‑list globs. Defaults include `.git`, `node_modules`, and STAN
-     * workspace rules. These are applied only when `includes` is empty.
+     * Deny‑list globs (hard denials). These always apply and take precedence over
+     * includes.
      */
     excludes?: string[];
     /** Optional callback for archive classifier warnings (engine remains silent by default). */
     onArchiveWarnings?: (text: string) => void;
-    /**
-     * High‑precedence re‑includes (subject to reserved denials and output exclusion).
-     * Anchors re-include paths even when excluded by `.gitignore` or `excludes`,
-     * but they never override reserved workspace denials:
-     * - `<stanPath>/diff/**`, `<stanPath>/patch/**`
-     * - `<stanPath>/output/{archive.tar,archive.diff.tar,archive.warnings.txt}`
-     * - `.git/**`
-     *
-     * @example
-     * ```ts
-     * // Force-include README.md even if repo excludes would drop it:
-     * await createArchive(cwd, '.stan', {
-     *   includes: [],
-     *   excludes: ['README.md'],
-     *   anchors: ['README.md'],
-     * });
-     * ```
-     */
-    anchors?: string[];
+    /** Optional callback for a deterministic selection report (engine remains silent by default). */
+    onSelectionReport?: (report: SelectionReport) => void;
 };
 /**
  * Create `stanPath/output/archive.tar` (or custom file name) from the repo root.
@@ -44,12 +101,53 @@ type CreateArchiveOptions = {
  * const tarPath = await createArchive(process.cwd(), '.stan', {
  *   includeOutputDir: false,
  *   excludes: ['**\/.tsbuild/**'],
- *   anchors: ['README.md', 'docs/index.md'], // re-include anchors
+ *   includes: ['README.md', 'docs/index.md'], // re-include even if gitignored
  * });
  * ```
  */
 declare function createArchive(cwd: string, stanPath: string, options?: CreateArchiveOptions): Promise<string>;
 
+/**
+ * Creates a full archive from an explicit allowlist of repo-relative files;
+ * excludes binaries via classifier, maintains `archive.prev.tar`, and surfaces
+ * warnings via callback; filesystem IO only; no console output.
+ * @module
+ */
+
+type CreateArchiveFromFilesOptions = {
+    /** When true, include the `stanPath/output` directory inside the archive. */
+    includeOutputDir?: boolean;
+    /**
+     * Archive file name. If provided without `.tar`, the suffix is added.
+     * Written to `stanPath/output/<fileName>`.
+     */
+    fileName?: string;
+    /** Optional callback for archive classifier warnings (engine remains silent by default). */
+    onArchiveWarnings?: (text: string) => void;
+    /** Optional callback for a deterministic selection report (engine remains silent by default). */
+    onSelectionReport?: (report: SelectionReport) => void;
+};
+
+/**
+ * Creates a "meta" archive (system docs + dependency meta, plus optional
+ * dependency state and repo-root base files); excludes staged payloads by
+ * omission and excludes `<stanPath>/system/.docs.meta.json`; filesystem IO only.
+ * @module
+ */
+
+declare function createMetaArchive(cwd: string, stanPath: string, selection?: {
+    includes?: string[];
+    excludes?: string[];
+}, options?: {
+    /** Optional callback for a deterministic selection report (engine remains silent by default). */
+    onSelectionReport?: (report: SelectionReport) => void;
+}): Promise<string>;
+
+/**
+ * Public defaults for STAN configuration (e.g. default `stanPath`); pure
+ * constants (no side effects).
+ * @module
+ */
 /** Public default STAN path for consumers and internal use. */
 declare const DEFAULT_STAN_PATH = ".stan";
 /** Default command to open modified files after patch apply. */
@@ -63,6 +161,11 @@ declare const DEFAULT_OPEN_COMMAND = "code -g {file}";
  */
 declare const findConfigPathSync: (cwd: string) => string | null;
 
+/**
+ * Public types for the engine config surface (`stan-core` block); used by
+ * loaders and callers; no runtime code.
+ * @module
+ */
 type ContextConfig = {
     /** STAN workspace directory (e.g., ".stan"). */
     stanPath: string;
@@ -102,7 +205,7 @@ declare const resolveStanPath: (cwd: string) => Promise<string>;
  *
  * Behavior:
  * - Always ensure `stanPath/output` and `stanPath/diff` exist.
- * - Also ensure `stanPath/patch` exists so archives can include it.
+ * - Also ensure `stanPath/patch` exists so patch tooling has a stable workspace.
  * - When `keep === false`, copy `output/archive.tar` to `diff/archive.prev.tar`
  *   if present, then clear only the `output` directory.
  *
@@ -113,6 +216,12 @@ declare const resolveStanPath: (cwd: string) => Promise<string>;
  */
 declare const ensureOutputDir: (cwd: string, stanPath: string, keep?: boolean) => Promise<string>;
 
+/**
+ * Creates diff archives and manages snapshot state; computes sha256 file hashes;
+ * writes snapshot/sentinel files; performs filesystem IO; no console output.
+ * @module
+ */
+
 type SnapshotUpdateMode = 'never' | 'createIfMissing' | 'replace';
 /**
  * Compute (and optionally update) the snapshot file in <stanPath>/diff/.
@@ -121,28 +230,25 @@ type SnapshotUpdateMode = 'never' | 'createIfMissing' | 'replace';
  * @param args - Object with:
  *   - cwd: Repo root.
  *   - stanPath: STAN workspace folder.
- *   - includes: Allow‑list globs (overrides excludes).
+ *   - includes: Additive allow‑list globs (can re-include gitignored files); excludes still win.
  *   - excludes: Deny‑list globs.
- *   - anchors: High‑precedence re‑includes (subject to reserved/output).
  *
  * @example
  * ```ts
- * // Seed snapshot using anchors to keep README.md even when excluded:
+ * // Seed snapshot using includes to bring back gitignored files:
  * await writeArchiveSnapshot({
  *   cwd: process.cwd(),
  *   stanPath: '.stan',
- *   excludes: ['README.md'],
- *   anchors: ['README.md'],
+ *   includes: ['README.md'],
  * });
  * ```
  * @returns Absolute path to the `.archive.snapshot.json` file.
  */
-declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, anchors, }: {
+declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, }: {
     cwd: string;
     stanPath: string;
     includes?: string[];
     excludes?: string[];
-    anchors?: string[];
 }): Promise<string>;
 /**
  * Create a diff tar at <stanPath>/output/<baseName>.diff.tar.
@@ -151,33 +257,30 @@ declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, ancho
  * - Snapshot update behavior is controlled by updateSnapshot.
  * - When includeOutputDirInDiff === true, also include the entire <stanPath>/output tree
  *   (excluding <stanPath>/diff and the two archive files) regardless of change list length.
- * - Always include <stanPath>/patch in the diff archive.
  *
  * @param args - Object with:
  *   - cwd: Repo root.
  *   - stanPath: STAN workspace folder.
  *   - baseName: Base archive name (e.g., `archive` -\> `archive.diff.tar`).
- *   - includes: Allow‑list globs (overrides excludes).
- *   - excludes: Deny‑list globs.
- *   - anchors: High‑precedence re‑includes (subject to reserved/output).
+ *   - includes: Additive allow‑list globs (can re-include gitignored files); excludes still win.
+ *   - excludes: Deny‑list globs (hard denials; take precedence over includes).
  *   - updateSnapshot: Controls when the snapshot file is replaced.
  *   - includeOutputDirInDiff: When true, include `stanPath/output` in the diff.
  * @returns `{ diffPath }` absolute path to the diff archive.
  *
  * @example
  * ```ts
- * // Diff archive with anchors to retain docs/overview.md:
+ * // Diff archive with includes to bring back gitignored files:
  * const { diffPath } = await createArchiveDiff({
  *   cwd: process.cwd(),
  *   stanPath: '.stan',
  *   baseName: 'archive',
- *   excludes: ['docs/**'],
- *   anchors: ['docs/overview.md'],
+ *   includes: ['docs/overview.md'],
  *   updateSnapshot: 'createIfMissing',
  * });
  * ```
  */
-declare function createArchiveDiff({ cwd, stanPath, baseName, includes, excludes, updateSnapshot, includeOutputDirInDiff, anchors, onArchiveWarnings, }: {
+declare function createArchiveDiff({ cwd, stanPath, baseName, includes, excludes, updateSnapshot, includeOutputDirInDiff, onArchiveWarnings, onSelectionReport, }: {
     cwd: string;
     stanPath: string;
     baseName: string;
@@ -185,32 +288,22 @@ declare function createArchiveDiff({ cwd, stanPath, baseName, includes, excludes
     excludes?: string[];
     updateSnapshot?: SnapshotUpdateMode;
     includeOutputDirInDiff?: boolean;
-    anchors?: string[];
     onArchiveWarnings?: (text: string) => void;
+    onSelectionReport?: (report: SelectionReport) => void;
 }): Promise<{
     diffPath: string;
 }>;
 
-/** src/stan/validate/response.ts
- * Response-format validator for assistant replies.
- *
- * Also validates optional "### File Ops" pre-ops block (verbs/arity/path rules).
- *
- * Checks (initial):
- * - One Patch per file.
- * - Each Patch block contains exactly one "diff --git a/<path> b/<path>" header.
- * - When both are present for a given file, "Patch" precedes "Full Listing".
- * - "## Commit Message" exists and is the final section.
- * - If any non‑docs Patch exists, there is also a Patch for ".stan/system/stan.todo.md".
- */
 /**
- * Kind tag for validator blocks. Exported so it appears in generated
- * documentation and to eliminate TypeDoc’s “referenced but not documented” warning.
+ * Types for response validation (blocks, options, results); used by parser and
+ * validator logic.
+ * @module
  */
 type BlockKind = 'patch' | 'full' | 'commit';
 type Block = {
     kind: BlockKind;
-    /** Repo-relative target path for patch/listing blocks; undefined for commit. */ path?: string;
+    /** Repo-relative target path for patch/listing blocks; undefined for commit. */
+    path?: string;
     /** Start index (character offset) in the source for ordering checks. */
     start: number;
     /** Block body (content between its heading and the next heading). */
@@ -221,19 +314,14 @@ type ValidationResult = {
     errors: string[];
     warnings: string[];
 };
-/** Validate an assistant reply body against response-format rules. */
-declare const validateResponseMessage: (text: string) => ValidationResult;
-/** Throw on validation failure (convenience API). */
-declare const validateOrThrow: (text: string) => void;
-declare const __internal: {
-    extractBlocks: (text: string) => Block[];
-    parseDiffHeaders: (body: string) => Array<{
-        a: string;
-        b: string;
-    }>;
-    isCommitLast: (text: string) => boolean;
+type ValidateResponseOptions = {
+    dependencyMode?: boolean;
+    stanPath?: string;
 };
 
+declare const validateResponseMessage: (text: string, options?: ValidateResponseOptions) => ValidationResult;
+declare const validateOrThrow: (text: string) => void;
+
 /**
  * Detect and clean a patch payload from clipboard/file/argument.
  * - Unwraps chat fences and BEGIN/END PATCH banners when they wrap the entire payload.
@@ -242,6 +330,10 @@ declare const __internal: {
  */
 declare const detectAndCleanPatch: (input: string) => string;
 
+/**
+ * Types for File Ops parsing and execution.
+ * @module
+ */
 type FileOp = {
     verb: 'mv';
     src: string;
@@ -266,20 +358,19 @@ type FileOpsPlan = {
 };
 type OpResult = {
     verb: FileOp['verb'];
-    src?: string;
-    dest?: string;
     status: 'ok' | 'failed';
-    errno?: string;
     message?: string;
 };
-/** Parse the optional "### File Ops" fenced block from a reply body. */
-declare const parseFileOpsBlock: (source: string) => FileOpsPlan;
+
 /** Execute File Ops with safety checks. Returns per-op results and overall ok. */
-declare const executeFileOps: (cwd: string, ops: FileOp[], dryRun?: boolean) => Promise<{
+declare const executeFileOps: (cwd: string, ops: FileOp[], dryRun?: boolean, stanPath?: string) => Promise<{
     ok: boolean;
     results: OpResult[];
 }>;
 
+/** Parse the optional "### File Ops" fenced block from a reply body. */
+declare const parseFileOpsBlock: (source: string, stanPath?: string) => FileOpsPlan;
+
 type AttemptCapture = {
     label: string;
     code: number;
@@ -293,6 +384,12 @@ type ApplyResult = {
     captures: AttemptCapture[];
 };
 
+/**
+ * Applies unified diffs via jsdiff ("diff" library) fallback; reads/writes
+ * files; preserves EOL; supports sandbox check-mode; refuses writes under
+ * <stanPath>/imports/**.
+ * @module
+ */
 type JsDiffOutcome = {
     okFiles: string[];
     failed: Array<{
@@ -307,6 +404,7 @@ declare const applyWithJsDiff: (args: {
     cleaned: string;
     check: boolean;
     sandboxRoot?: string;
+    stanPath?: string;
 }) => Promise<JsDiffOutcome>;
 
 type PipelineOutcome = {
@@ -322,6 +420,8 @@ declare const applyPatchPipeline: (args: {
     check: boolean;
     /** Attempt order; defaults to [1,0] (p1 then p0). */
     stripOrder?: number[];
+    /** When provided, enables protection rules scoped to this workspace (e.g., imports read-only). */
+    stanPath?: string;
 }) => Promise<PipelineOutcome>;
 
 type ImportsMap = Record<string, string[]>;
@@ -341,6 +441,554 @@ declare const prepareImports: (args: {
     onStage?: (label: string, files: string[]) => void;
 }) => Promise<void>;
 
+/**
+ * Defines dependency graph meta/state schemas (Zod) for context mode; pure
+ * validation/types; no filesystem IO; deterministic formats.
+ *
+ * Dependency graph mode: on-disk JSON formats for:
+ * - .stan/context/dependency.state.json (assistant-authored selection intent)
+ * - .stan/context/dependency.meta.json (assistant-facing dependency graph)
+ *
+ * Requirements:
+ * - Node IDs are repo-relative POSIX paths.
+ * - State entries support string | [nodeId, depth] | [nodeId, depth, edgeKinds[]]
+ *   with defaults depth=0, edgeKinds=['runtime','type','dynamic'].
+ * - Meta may include locatorAbs ONLY for abs/outside-root nodes.
+ * @module
+ */
+
+/** Edge kinds recorded in dependency meta and used by dependency state. */
+declare const dependencyEdgeTypeSchema: z.ZodEnum<{
+    type: "type";
+    runtime: "runtime";
+    dynamic: "dynamic";
+}>;
+type DependencyEdgeType = z.infer<typeof dependencyEdgeTypeSchema>;
+/** A raw entry as stored in dependency.state.json. */
+declare const dependencyStateEntrySchema: z.ZodUnion<readonly [z.ZodString, z.ZodTuple<[z.ZodString, z.ZodNumber], null>, z.ZodTuple<[z.ZodString, z.ZodNumber, z.ZodArray<z.ZodEnum<{
+    type: "type";
+    runtime: "runtime";
+    dynamic: "dynamic";
+}>>], null>]>;
+type DependencyStateEntry = z.infer<typeof dependencyStateEntrySchema>;
+/** Normalized internal representation of a state entry (defaults applied). */
+type NormalizedDependencyStateEntry = {
+    nodeId: string;
+    depth: number;
+    edgeKinds: DependencyEdgeType[];
+};
+declare const dependencyStateFileSchema: z.ZodObject<{
+    include: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodTuple<[z.ZodString, z.ZodNumber], null>, z.ZodTuple<[z.ZodString, z.ZodNumber, z.ZodArray<z.ZodEnum<{
+        type: "type";
+        runtime: "runtime";
+        dynamic: "dynamic";
+    }>>], null>]>>;
+    exclude: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodTuple<[z.ZodString, z.ZodNumber], null>, z.ZodTuple<[z.ZodString, z.ZodNumber, z.ZodArray<z.ZodEnum<{
+        type: "type";
+        runtime: "runtime";
+        dynamic: "dynamic";
+    }>>], null>]>>>;
+}, z.core.$strict>;
+type DependencyStateFile = z.infer<typeof dependencyStateFileSchema>;
+/** Parse and normalize state entries (defaults applied; stable edgeKinds). */
+declare const parseDependencyStateFile: (raw: unknown) => {
+    include: NormalizedDependencyStateEntry[];
+    exclude: NormalizedDependencyStateEntry[];
+};
+/** Dependency meta edge record (minimal, assistant-facing). */
+declare const dependencyMetaEdgeSchema: z.ZodObject<{
+    target: z.ZodString;
+    kind: z.ZodEnum<{
+        type: "type";
+        runtime: "runtime";
+        dynamic: "dynamic";
+    }>;
+    resolution: z.ZodOptional<z.ZodEnum<{
+        explicit: "explicit";
+        implicit: "implicit";
+    }>>;
+}, z.core.$strict>;
+type DependencyMetaEdge = z.infer<typeof dependencyMetaEdgeSchema>;
+/** Dependency meta node (assistant-facing). */
+declare const dependencyMetaNodeSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        source: "source";
+        external: "external";
+        builtin: "builtin";
+        missing: "missing";
+    }>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        size: z.ZodOptional<z.ZodNumber>;
+        hash: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    description: z.ZodOptional<z.ZodString>;
+    locatorAbs: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type DependencyMetaNode = z.infer<typeof dependencyMetaNodeSchema>;
+/**
+ * Dependency meta file (assistant-facing).
+ *
+ * Notes:
+ * - node IDs are repo-relative POSIX paths.
+ * - edges is a complete map (key exists for every nodeId; empty array OK).
+ */
+declare const dependencyMetaFileSchema: z.ZodObject<{
+    schemaVersion: z.ZodNumber;
+    nodes: z.ZodRecord<z.ZodString, z.ZodObject<{
+        kind: z.ZodEnum<{
+            source: "source";
+            external: "external";
+            builtin: "builtin";
+            missing: "missing";
+        }>;
+        metadata: z.ZodOptional<z.ZodObject<{
+            size: z.ZodOptional<z.ZodNumber>;
+            hash: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        description: z.ZodOptional<z.ZodString>;
+        locatorAbs: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    edges: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+        target: z.ZodString;
+        kind: z.ZodEnum<{
+            type: "type";
+            runtime: "runtime";
+            dynamic: "dynamic";
+        }>;
+        resolution: z.ZodOptional<z.ZodEnum<{
+            explicit: "explicit";
+            implicit: "implicit";
+        }>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type DependencyMetaFile = z.infer<typeof dependencyMetaFileSchema>;
+
+/**
+ * Computes context-mode allowlist plans (Base + dependency closure), applying
+ * explicit excludes as hard denials and identifying stageable external nodeIds
+ * under <stanPath>/context/npm/** and <stanPath>/context/abs/**; filesystem IO
+ * only; no console output.
+ * @module
+ */
+
+type ContextModeSelection = {
+    includes?: string[];
+    excludes?: string[];
+};
+type ContextAllowlistPlan = {
+    /** Base (system + dependency meta/state + repo-root base files). */
+    baseFiles: string[];
+    /** All selected nodeIds from dependency state closure (after excludes/reserved). */
+    selectedNodeIds: string[];
+    /** External nodeIds that must be staged into <stanPath>/context/**. */
+    stageNodeIds: string[];
+    /** Final allowlist (Base + selected closure; after excludes/reserved). */
+    allowlistFiles: string[];
+    /** True when dependency.state.json existed on disk and was used implicitly. */
+    usedDiskState: boolean;
+};
+/**
+ * Compute context-mode Base and allowlist selection.
+ *
+ * Base definition (v1):
+ * - system docs under <stanPath>/system/** (excluding <stanPath>/system/.docs.meta.json)
+ * - dependency meta at <stanPath>/context/dependency.meta.json (required)
+ * - dependency state at <stanPath>/context/dependency.state.json (when present)
+ * - plus repo-root files selected by current selection config (top-level files only)
+ *
+ * Allowlist:
+ * - Base + selected dependency closure (repo-local nodeIds + staged externals)
+ * - apply explicit excludes as hard denials
+ * - reserved denials always win
+ */
+declare const computeContextAllowlistPlan: (args: {
+    cwd: string;
+    stanPath: string;
+    meta: Pick<DependencyMetaFile, "nodes" | "edges">;
+    state?: unknown;
+    selection?: ContextModeSelection;
+}) => Promise<ContextAllowlistPlan>;
+
+/**
+ * Types for dependency graph build and normalization.
+ * @module
+ */
+
+type BuildDependencyMetaArgs = {
+    cwd: string;
+    stanPath: string;
+    selection?: {
+        includes?: string[];
+        excludes?: string[];
+    };
+    nodeDescriptionLimit?: number;
+    nodeDescriptionTags?: string[];
+    maxErrors?: number;
+};
+type NodeSource = {
+    kind: 'repo';
+} | {
+    kind: 'npm';
+    sourceAbs: string;
+    pkgName: string;
+    pkgVersion: string;
+    pathInPackage: string;
+} | {
+    kind: 'abs';
+    sourceAbs: string;
+    locatorAbs: string;
+};
+type BuildDependencyMetaResult = {
+    meta: DependencyMetaFile;
+    sources: Record<string, NodeSource>;
+    warnings: string[];
+    stats?: {
+        modules: number;
+        edges: number;
+        dirty: number;
+    };
+};
+
+declare const buildDependencyMeta: (args: BuildDependencyMetaArgs) => Promise<BuildDependencyMetaResult>;
+
+type StageDependencyContextArgs = {
+    cwd: string;
+    stanPath: string;
+    /** Parsed dependency meta (usually produced by buildDependencyMeta). */
+    meta: {
+        nodes: Record<string, DependencyMetaNode | undefined>;
+    };
+    /**
+     * Optional source map (usually from buildDependencyMeta). If absent, abs
+     * nodes can still be staged via meta.nodes[nodeId].locatorAbs.
+     */
+    sources?: Record<string, NodeSource>;
+    /**
+     * Optional subset of nodeIds to stage (e.g., a selection closure).
+     * If omitted, stages all nodeIds present in sources (filtered to stageable).
+     */
+    nodeIds?: string[];
+    /**
+     * When true, clears <stanPath>/context/npm and <stanPath>/context/abs before staging.
+     * Does NOT touch dependency.meta.json or dependency.state.json.
+     */
+    clean?: boolean;
+};
+type StagedEntry = {
+    nodeId: string;
+    sourceAbs: string;
+    destAbs: string;
+    hash: string;
+    size: number;
+};
+type StageDependencyContextResult = {
+    staged: StagedEntry[];
+    skipped: string[];
+};
+declare const stageDependencyContext: (args: StageDependencyContextArgs) => Promise<StageDependencyContextResult>;
+
+/**
+ * Orchestrates dependency-graph archive flows (stage context + force includes);
+ * calls archive/diff helpers; filesystem IO only; no console output.
+ *
+ * Dependency graph mode: orchestration helpers for CLI-facing archive flows.
+ *
+ * Requirements:
+ * - Stage dependency external bytes (npm + abs) into <stanPath>/context/** before archiving.
+ * - Prefer staging ONLY the selected nodeId set derived from dependency state closure to avoid bloat.
+ * - Ensure <stanPath>/context/** is included in archives even when gitignored (use includes).
+ * - No console I/O; keep behavior deterministic.
+ * @module
+ */
+
+type DependencyContextMeta = Pick<DependencyMetaFile, 'edges'> & {
+    nodes: Record<string, DependencyMetaNode | undefined>;
+};
+type DependencyContextInputs = {
+    meta: DependencyContextMeta;
+    /**
+     * Dependency selection state (assistant-authored).
+     * When present, used to compute a selected closure and stage only those nodes.
+     * When absent, staging falls back to "all stageable nodes in sources".
+     */
+    state?: unknown;
+    /**
+     * Node source locators (produced by buildDependencyMeta).
+     * Strongly recommended for npm nodes; abs nodes may also be staged using locatorAbs from meta.
+     */
+    sources?: Record<string, NodeSource>;
+};
+type PrepareDependencyContextResult = {
+    /** Include globs required to include <stanPath>/context/** even if gitignored. */
+    includes: string[];
+    /** Node IDs selected by state closure (empty when state not provided). */
+    selectedNodeIds: string[];
+    /** Node IDs that should be staged (subset of selected, stageable only). */
+    stageNodeIds: string[];
+};
+declare const prepareDependencyContext: (args: {
+    stanPath: string;
+    meta: DependencyContextMeta;
+    state?: unknown;
+    /** Optional override when state is omitted (default: stage all stageable nodes in sources). */
+    nodeIdsWhenNoState?: string[];
+}) => PrepareDependencyContextResult;
+type StagePreparedDependencyContextResult = PrepareDependencyContextResult & {
+    stage: StageDependencyContextResult;
+};
+declare const stagePreparedDependencyContext: (args: {
+    cwd: string;
+    stanPath: string;
+    meta: DependencyContextMeta;
+    sources?: Record<string, NodeSource>;
+    plan: PrepareDependencyContextResult;
+    clean?: boolean;
+}) => Promise<StagePreparedDependencyContextResult>;
+type CreateArchiveWithDependencyContextResult = StagePreparedDependencyContextResult & {
+    archivePath: string;
+};
+declare const createArchiveWithDependencyContext: (args: {
+    cwd: string;
+    stanPath: string;
+    dependency: DependencyContextInputs & {
+        clean?: boolean;
+    };
+    archive?: CreateArchiveOptions;
+}) => Promise<CreateArchiveWithDependencyContextResult>;
+type CreateArchiveDiffWithDependencyContextResult = StagePreparedDependencyContextResult & {
+    diffPath: string;
+};
+declare const createArchiveDiffWithDependencyContext: (args: {
+    cwd: string;
+    stanPath: string;
+    dependency: DependencyContextInputs & {
+        clean?: boolean;
+    };
+    diff: {
+        baseName: string;
+        includes?: string[];
+        excludes?: string[];
+        updateSnapshot?: SnapshotUpdateMode;
+        includeOutputDirInDiff?: boolean;
+        onArchiveWarnings?: (text: string) => void;
+    };
+}) => Promise<CreateArchiveDiffWithDependencyContextResult>;
+
+/**
+ * Computes a deterministic size report for a context-mode allowlist (Base +
+ * dependency closure). Uses dependency meta `metadata.size` (bytes) when
+ * available and falls back to `stat()` for repo files; no file-body reads.
+ * @module
+ */
+
+type BudgetSource = 'meta' | 'stat' | 'missing';
+type BudgetEntry = {
+    /** Repo-relative POSIX path. */
+    path: string;
+    /** Size in bytes (0 when unknown/missing). */
+    bytes: number;
+    /** Where the bytes estimate came from. */
+    source: BudgetSource;
+};
+type ContextAllowlistBudget = {
+    /** Total number of allowlisted paths. */
+    files: number;
+    /** Total bytes across allowlisted paths. */
+    totalBytes: number;
+    /** Deterministic heuristic: totalBytes / 4. */
+    estimatedTokens: number;
+    /** Budgeting breakdown by set membership. */
+    breakdown: {
+        baseOnly: {
+            files: number;
+            bytes: number;
+        };
+        closureOnly: {
+            files: number;
+            bytes: number;
+        };
+        overlap: {
+            files: number;
+            bytes: number;
+        };
+    };
+    /** Largest allowlisted entries by byte size (descending). */
+    largest: BudgetEntry[];
+    /** Deterministic warnings (missing sizes, missing files, invalid metadata). */
+    warnings: string[];
+};
+/**
+ * Summarize the byte size of a context allowlist deterministically.
+ *
+ * @param args - Inputs object (repo root, allowlist plan, dependency meta nodes
+ * map, and optional max count for largest entries).
+ */
+declare const summarizeContextAllowlistBudget: (args: {
+    cwd: string;
+    plan: {
+        baseFiles: ReadonlyArray<string>;
+        selectedNodeIds: ReadonlyArray<string>;
+        allowlistFiles: ReadonlyArray<string>;
+    };
+    meta: Pick<DependencyMetaFile, "nodes">;
+    topN?: number;
+}) => Promise<ContextAllowlistBudget>;
+
+/**
+ * Orchestrates context-mode allowlist-only archiving (Base + dependency closure)
+ * by staging selected external node bytes under <stanPath>/context/** and then
+ * creating full/diff archives from the computed allowlist; filesystem IO only;
+ * no console output.
+ * @module
+ */
+
+type CreateContextArchiveOptions = Pick<CreateArchiveFromFilesOptions, 'fileName' | 'onArchiveWarnings'> & {
+    /** Context mode should remain allowlist-only; output dir inclusion is rarely desired. */
+    includeOutputDir?: false;
+};
+type CreateContextArchiveResult = {
+    archivePath: string;
+    plan: Awaited<ReturnType<typeof computeContextAllowlistPlan>>;
+    stage: StageDependencyContextResult;
+};
+declare const createContextArchiveWithDependencyContext: (args: {
+    cwd: string;
+    stanPath: string;
+    dependency: {
+        meta: Pick<DependencyMetaFile, "nodes" | "edges">;
+        state?: unknown;
+        sources?: Record<string, NodeSource>;
+        clean?: boolean;
+    };
+    selection?: ContextModeSelection;
+    archive?: CreateContextArchiveOptions;
+}) => Promise<CreateContextArchiveResult>;
+type CreateContextArchiveDiffResult = {
+    diffPath: string;
+    plan: Awaited<ReturnType<typeof computeContextAllowlistPlan>>;
+    stage: StageDependencyContextResult;
+};
+declare const createContextArchiveDiffWithDependencyContext: (args: {
+    cwd: string;
+    stanPath: string;
+    dependency: {
+        meta: Pick<DependencyMetaFile, "nodes" | "edges">;
+        state?: unknown;
+        sources?: Record<string, NodeSource>;
+        clean?: boolean;
+    };
+    selection?: ContextModeSelection;
+    diff: {
+        baseName: string;
+        updateSnapshot?: SnapshotUpdateMode;
+        includeOutputDirInDiff?: boolean;
+        onArchiveWarnings?: (text: string) => void;
+    };
+}) => Promise<CreateContextArchiveDiffResult>;
+
+/**
+ * Computes dependency selection closure from meta+state (depth + edgeKinds);
+ * deterministic BFS; pure graph traversal; no filesystem IO.
+ *
+ * Dependency graph mode: compute selected node IDs from:
+ * - dependency.meta.json edges
+ * - dependency.state.json include/exclude entries
+ *
+ * Requirements:
+ * - Depth semantics: 0 =\> node only (no traversal).
+ * - Traverse outgoing edges only, restricted by edgeKinds.
+ * - Deterministic selection: stable ordering across runs for identical inputs.
+ * - Excludes win: subtract after includes using same traversal semantics.
+ * @module
+ */
+
+/**
+ * Expand a single state entry into a set of nodeIds (node + closure).
+ * BFS is used so depth is intuitive and deterministic.
+ */
+declare const expandEntry: (meta: Pick<DependencyMetaFile, "edges">, entry: NormalizedDependencyStateEntry) => Set<string>;
+/**
+ * Compute final selected nodeIds from include/exclude entries.
+ * Excludes win (subtract after includes).
+ */
+declare const computeSelectedNodeIds: (args: {
+    meta: Pick<DependencyMetaFile, "edges">;
+    include: NormalizedDependencyStateEntry[];
+    exclude: NormalizedDependencyStateEntry[];
+}) => string[];
+
+/**
+ * Public types for dependency selection validation (undo/redo seam); used by
+ * validators and callers; no runtime code.
+ * @module
+ */
+type DependencyValidationMismatch = {
+    nodeId: string;
+    kind: 'npm';
+    reason: 'invalid-nodeId' | 'meta-missing' | 'metadata-missing' | 'package-not-found' | 'package-version-mismatch' | 'file-missing' | 'hash-mismatch' | 'size-mismatch';
+    pkgName?: string;
+    pkgVersion?: string;
+    pathInPackage?: string;
+    expectedHash?: string;
+    actualHash?: string;
+    expectedSize?: number;
+    actualSize?: number;
+    candidates?: string[];
+} | {
+    nodeId: string;
+    kind: 'abs';
+    reason: 'meta-missing' | 'metadata-missing' | 'locator-missing' | 'file-missing' | 'hash-mismatch' | 'size-mismatch';
+    locatorAbs?: string;
+    expectedHash?: string;
+    actualHash?: string;
+    expectedSize?: number;
+    actualSize?: number;
+};
+type ValidateDependencySelectionResult = {
+    ok: boolean;
+    selectedNodeIds: string[];
+    checkedNodeIds: string[];
+    mismatches: DependencyValidationMismatch[];
+};
+
+/**
+ * Validate that the selected dependency set (from meta+state closure) can be
+ * satisfied by the current environment.
+ *
+ * - Computes selected node IDs from meta+state closure (excludes win).
+ * - Validates external nodes only:
+ *   - npm nodes under `<stanPath>/context/npm/**` by locating `<pkgName>\@<pkgVersion>`
+ *     in the current install and hashing `<pathInPackage>`.
+ *   - abs nodes under `<stanPath>/context/abs/**` by hashing `locatorAbs`.
+ *
+ * @param args - Validation inputs.
+ * @returns Validation result with deterministic mismatches.
+ */
+declare const validateDependencySelection: (args: {
+    cwd: string;
+    stanPath: string;
+    meta: Pick<DependencyMetaFile, "nodes" | "edges">;
+    state: unknown;
+}) => Promise<ValidateDependencySelectionResult>;
+/**
+ * Validate dependency selection and throw on mismatch (strict undo/redo seam).
+ *
+ * @param args - Validation inputs.
+ * @returns Resolves when validation passes; throws when mismatches exist.
+ */
+declare const validateDependencySelectionOrThrow: (args: {
+    cwd: string;
+    stanPath: string;
+    meta: Pick<DependencyMetaFile, "nodes" | "edges">;
+    state: unknown;
+}) => Promise<void>;
+
+declare const writeDependencyMetaFile: (args: {
+    cwd: string;
+    stanPath: string;
+    meta: DependencyMetaFile;
+}) => Promise<string>;
+
 /**
  * Compile an engine‑parity matcher that returns true when any pattern matches.
  *
@@ -374,5 +1022,5 @@ declare const assembleSystemMonolith: (cwd: string, stanPath: string) => Promise
 
 declare const CORE_VERSION: string;
 
-export { CORE_VERSION, DEFAULT_OPEN_COMMAND, DEFAULT_STAN_PATH, __internal, applyPatchPipeline, applyWithJsDiff, assembleSystemMonolith, createArchive, createArchiveDiff, detectAndCleanPatch, ensureOutputDir, executeFileOps, findConfigPathSync, getPackagedSystemPromptPath, loadConfig, loadConfigSync, makeGlobMatcher, parseFileOpsBlock, prepareImports, resolveStanPath, resolveStanPathSync, validateOrThrow, validateResponseMessage, writeArchiveSnapshot };
-export type { ApplyResult, AssembleResult, AttemptCapture, Block, BlockKind, ContextConfig, CreateArchiveOptions, FileOp, FileOpsPlan, ImportsMap, JsDiffOutcome, OpResult, PipelineOutcome, SnapshotUpdateMode, ValidationResult };
+export { CORE_VERSION, DEFAULT_OPEN_COMMAND, DEFAULT_STAN_PATH, applyPatchPipeline, applyWithJsDiff, assembleSystemMonolith, buildDependencyMeta, computeContextAllowlistPlan, computeSelectedNodeIds, createArchive, createArchiveDiff, createArchiveDiffWithDependencyContext, createArchiveWithDependencyContext, createContextArchiveDiffWithDependencyContext, createContextArchiveWithDependencyContext, createMetaArchive, dependencyEdgeTypeSchema, dependencyMetaEdgeSchema, dependencyMetaFileSchema, dependencyMetaNodeSchema, dependencyStateEntrySchema, dependencyStateFileSchema, detectAndCleanPatch, ensureOutputDir, executeFileOps, expandEntry, findConfigPathSync, getPackagedSystemPromptPath, loadConfig, loadConfigSync, makeGlobMatcher, parseDependencyStateFile, parseFileOpsBlock, prepareDependencyContext, prepareImports, resolveStanPath, resolveStanPathSync, stageDependencyContext, stagePreparedDependencyContext, summarizeContextAllowlistBudget, validateDependencySelection, validateDependencySelectionOrThrow, validateOrThrow, validateResponseMessage, writeArchiveSnapshot, writeDependencyMetaFile };
+export type { ApplyResult, AssembleResult, AttemptCapture, Block, BlockKind, BudgetEntry, BudgetSource, BuildDependencyMetaArgs, BuildDependencyMetaResult, ContextAllowlistBudget, ContextAllowlistPlan, ContextConfig, ContextModeSelection, CreateArchiveDiffWithDependencyContextResult, CreateArchiveFromFilesOptions, CreateArchiveOptions, CreateArchiveWithDependencyContextResult, CreateContextArchiveDiffResult, CreateContextArchiveOptions, CreateContextArchiveResult, DependencyContextInputs, DependencyContextMeta, DependencyEdgeType, DependencyMetaEdge, DependencyMetaFile, DependencyMetaNode, DependencyStateEntry, DependencyStateFile, DependencyValidationMismatch, FileOp, FileOpsPlan, ImportsMap, JsDiffOutcome, NodeSource, NormalizedDependencyStateEntry, OpResult, PipelineOutcome, PrepareDependencyContextResult, SelectionReport, SelectionReportCounts, SnapshotUpdateMode, StageDependencyContextArgs, StageDependencyContextResult, StagePreparedDependencyContextResult, StagedEntry, ValidateDependencySelectionResult, ValidateResponseOptions, ValidationResult };