@karmaniverous/stan-core 0.9.1 → 0.9.2

package/dist/stan.system.md

@@ -853,7 +853,7 @@ diff --git a/new/path/to/file/a.ts b/new/path/to/file/a.ts
 
 - Primary artifacts live under `<stanPath>/output/`:
   - `archive.tar` — full snapshot of files to read (default). In `stan run --context --meta`, this path is used for the META archive (system + dependency meta + dependency state) and a diff archive is not written.
-  - `archive.diff.tar` — only files changed since the previous snapshot. In `stan run --context` (non-meta), this is the only archive written; it may include `dependency.meta.json` and/or `dependency.state.json` when those files change.
+  - `archive.diff.tar` — only files changed since the previous snapshot. In `stan run --context` (non-meta), this is the DIFF allowlist context archive; the FULL allowlist context archive is also written as `archive.tar`.
   - Script outputs (`test.txt`, `lint.txt`, `typecheck.txt`, `build.txt`) — deterministic stdout/stderr dumps from configured scripts. When `--combine` is used, these outputs are placed inside the archives and removed from disk.
 - When attaching artifacts for chat, prefer attaching `<stanPath>/output/archive.tar` (and `<stanPath>/output/archive.diff.tar` when present). If `--combine` was not used, you may also attach the text outputs individually.
 - Important: Inside any attached archive, contextual files are located in the directory matching the `stanPath` key from `stan.config.*` (default `.stan`). The bootloader resolves this automatically.
@@ -946,7 +946,7 @@ Dependency artifacts (workspace; gitignored):
 Archive outputs (under `<stanPath>/output/`):
 
 - `<stanPath>/output/archive.tar` (full by default; META when `stan run --context --meta`)
-- `<stanPath>/output/archive.diff.tar` (diff; only archive produced by `stan run --context` (non-meta))
+- `<stanPath>/output/archive.diff.tar` (diff; written by `stan run` and by `stan run --context` (non-meta))
 - In `stan run --context --meta`, `archive.diff.tar` is not written.
   - The META archive contains system files + dependency meta + dependency state (the host writes `{ "v": 2, "i": [] }` before archiving so the assistant starts from a clean slate).
   - It excludes staged payloads by omission and never includes `dependency.map.json` (host-private; reserved denial).
@@ -1025,7 +1025,7 @@ The META archive is intended for the start of a thread:
 
 - It contains system docs + `dependency.meta.json` + `dependency.state.json` (v2 empty written by the host).
 - It excludes staged dependency payloads by omission.
-- After the thread is started, `stan run --context` (non-meta) should rely on the diff archive (`archive.diff.tar`) for subsequent turns.
+- After the thread is started, `stan run --context` (non-meta) writes BOTH a FULL allowlist context archive (`archive.tar`) and a DIFF allowlist context archive (`archive.diff.tar`) for subsequent turns.
 
 ## Assistant guidance (anti-bloat)
 

package/dist/types/index.d.ts

@@ -242,6 +242,7 @@ type SnapshotUpdateMode = 'never' | 'createIfMissing' | 'replace';
  *   - stanPath: STAN workspace folder.
  *   - includes: Additive allow‑list globs (can re-include gitignored files); excludes still win.
  *   - excludes: Deny‑list globs.
+ *   - snapshotFileName: Optional snapshot file name override under `<stanPath>/diff/`.
  *
  * @example
  * ```ts
@@ -254,11 +255,12 @@ type SnapshotUpdateMode = 'never' | 'createIfMissing' | 'replace';
  * ```
  * @returns Absolute path to the `.archive.snapshot.json` file.
  */
-declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, }: {
+declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, snapshotFileName, }: {
     cwd: string;
     stanPath: string;
     includes?: string[];
     excludes?: string[];
+    snapshotFileName?: string;
 }): Promise<string>;
 /**
  * Create a diff tar at <stanPath>/output/<baseName>.diff.tar.
@@ -267,6 +269,7 @@ declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, }: {
  * - 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.
+ * - Snapshot location can be overridden via snapshotFileName (defaults to `.archive.snapshot.json`).
  *
  * @param args - Object with:
  *   - cwd: Repo root.
@@ -275,6 +278,7 @@ declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, }: {
  *   - 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.
+ *   - snapshotFileName: Optional snapshot file name override under `<stanPath>/diff/`.
  *   - includeOutputDirInDiff: When true, include `stanPath/output` in the diff.
  * @returns `{ diffPath }` absolute path to the diff archive.
  *
@@ -290,13 +294,63 @@ declare function writeArchiveSnapshot({ cwd, stanPath, includes, excludes, }: {
  * });
  * ```
  */
-declare function createArchiveDiff({ cwd, stanPath, baseName, includes, excludes, updateSnapshot, includeOutputDirInDiff, onArchiveWarnings, onSelectionReport, }: {
+declare function createArchiveDiff({ cwd, stanPath, baseName, includes, excludes, updateSnapshot, snapshotFileName, includeOutputDirInDiff, onArchiveWarnings, onSelectionReport, }: {
     cwd: string;
     stanPath: string;
     baseName: string;
     includes?: string[];
     excludes?: string[];
     updateSnapshot?: SnapshotUpdateMode;
+    snapshotFileName?: string;
+    includeOutputDirInDiff?: boolean;
+    onArchiveWarnings?: (text: string) => void;
+    onSelectionReport?: (report: SelectionReport) => void;
+}): Promise<{
+    diffPath: string;
+}>;
+
+/**
+ * Creates diff archives from an explicit allowlist of repo-relative files and
+ * manages snapshot state; excludes binaries via classifier; filesystem IO only;
+ * no console output.
+ * @module
+ */
+
+/**
+ * Write a snapshot file under `<stanPath>/diff/` for an explicit allowlist.
+ *
+ * This allows callers (e.g., CLI) to maintain distinct snapshot baselines for
+ * different selection universes (denylist vs allowlist/context) by using
+ * different snapshot file names.
+ *
+ * @param args - Inputs including repo root, stanPath, allowlist files, and an
+ * optional snapshot file name override.
+ * @returns Absolute path to the written snapshot file.
+ */
+declare function writeArchiveSnapshotFromFiles(args: {
+    cwd: string;
+    stanPath: string;
+    relFiles: string[];
+    snapshotFileName?: string;
+}): Promise<string>;
+/**
+ * Create a diff tar at <stanPath>/output/<baseName>.diff.tar from an explicit
+ * allowlist of repo-relative files.
+ *
+ * Snapshot semantics:
+ * - Snapshot path: <stanPath>/diff/.archive.snapshot.json
+ * - When snapshot exists: include only changed files (within allowlist).
+ * - When snapshot missing: include full allowlist (diff equals full selection).
+ * - No-changes case: write <stanPath>/diff/.stan_no_changes and include it.
+ * - Snapshot location can be overridden via snapshotFileName (defaults to `.archive.snapshot.json`).
+ */
+declare function createArchiveDiffFromFiles(args: {
+    cwd: string;
+    stanPath: string;
+    baseName: string;
+    relFiles: string[];
+    updateSnapshot?: SnapshotUpdateMode;
+    snapshotFileName?: string;
     includeOutputDirInDiff?: boolean;
     onArchiveWarnings?: (text: string) => void;
     onSelectionReport?: (report: SelectionReport) => void;
@@ -814,6 +868,7 @@ declare const createContextArchiveDiffWithDependencyContext: (args: {
     diff: {
         baseName: string;
         updateSnapshot?: SnapshotUpdateMode;
+        snapshotFileName?: string;
         includeOutputDirInDiff?: boolean;
         onArchiveWarnings?: (text: string) => void;
     };
@@ -940,5 +995,5 @@ declare const assembleSystemMonolith: (cwd: string, stanPath: string) => Promise
 
 declare const CORE_VERSION: string;
 
-export { CORE_VERSION, DEFAULT_OPEN_COMMAND, DEFAULT_STAN_PATH, applyPatchPipeline, applyWithJsDiff, assembleSystemMonolith, buildDependencyMeta, computeContextAllowlistPlan, computeSelectedNodeIds, createArchive, createArchiveDiff, createArchiveDiffWithDependencyContext, createArchiveWithDependencyContext, createContextArchiveDiffWithDependencyContext, createContextArchiveWithDependencyContext, createMetaArchive, dependencyMapFileSchema, dependencyMapNodeSchema, dependencyMetaFileSchema, dependencyMetaNodeSchema, dependencyStateEntrySchema, dependencyStateFileSchema, detectAndCleanPatch, ensureOutputDir, executeFileOps, expandEntry, findConfigPathSync, getPackagedSystemPromptPath, loadConfig, loadConfigSync, makeGlobMatcher, parseDependencyStateFile, parseFileOpsBlock, prepareDependencyContext, prepareImports, resolveStanPath, resolveStanPathSync, stageDependencyContext, stagePreparedDependencyContext, summarizeContextAllowlistBudget, validateDependencySelection, validateDependencySelectionOrThrow, writeArchiveSnapshot, writeDependencyMapFile, writeDependencyMetaFile };
+export { CORE_VERSION, DEFAULT_OPEN_COMMAND, DEFAULT_STAN_PATH, applyPatchPipeline, applyWithJsDiff, assembleSystemMonolith, buildDependencyMeta, computeContextAllowlistPlan, computeSelectedNodeIds, createArchive, createArchiveDiff, createArchiveDiffFromFiles, createArchiveDiffWithDependencyContext, createArchiveWithDependencyContext, createContextArchiveDiffWithDependencyContext, createContextArchiveWithDependencyContext, createMetaArchive, dependencyMapFileSchema, dependencyMapNodeSchema, dependencyMetaFileSchema, dependencyMetaNodeSchema, dependencyStateEntrySchema, dependencyStateFileSchema, detectAndCleanPatch, ensureOutputDir, executeFileOps, expandEntry, findConfigPathSync, getPackagedSystemPromptPath, loadConfig, loadConfigSync, makeGlobMatcher, parseDependencyStateFile, parseFileOpsBlock, prepareDependencyContext, prepareImports, resolveStanPath, resolveStanPathSync, stageDependencyContext, stagePreparedDependencyContext, summarizeContextAllowlistBudget, validateDependencySelection, validateDependencySelectionOrThrow, writeArchiveSnapshot, writeArchiveSnapshotFromFiles, writeDependencyMapFile, writeDependencyMetaFile };
 export type { ApplyResult, AssembleResult, AttemptCapture, BudgetEntry, BudgetSource, BuildDependencyMetaArgs, BuildDependencyMetaResult, ContextAllowlistBudget, ContextAllowlistPlan, ContextConfig, ContextModeSelection, CreateArchiveDiffWithDependencyContextResult, CreateArchiveFromFilesOptions, CreateArchiveOptions, CreateArchiveWithDependencyContextResult, CreateContextArchiveDiffResult, CreateContextArchiveOptions, CreateContextArchiveResult, DependencyContextInputs, DependencyMapFile, DependencyMapNode, DependencyMetaFile, DependencyMetaNode, DependencyStateEntry, DependencyStateFile, DependencyValidationMismatch, FileOp, FileOpsPlan, ImportsMap, JsDiffOutcome, NodeSource, NormalizedDependencyStateEntry, OpResult, PipelineOutcome, PrepareDependencyContextResult, SelectionReport, SelectionReportCounts, SnapshotUpdateMode, StageDependencyContextArgs, StageDependencyContextResult, StagePreparedDependencyContextResult, StagedEntry, ValidateDependencySelectionResult };

package/package.json

@@ -151,5 +151,5 @@
   },
   "type": "module",
   "types": "dist/types/index.d.ts",
-  "version": "0.9.1"
+  "version": "0.9.2"
 }