@karmaniverous/stan-core 0.9.0 → 0.9.2

package/dist/stan.system.md

@@ -570,7 +570,7 @@ Rules
 
 - Canonical path: `<stanPath>/system/stan.scratch.md`.
 - Base-always: the scratch file is always part of the Base set for archiving:
-  - It MUST be present in `archive.meta.tar` and full archives.
+  - It MUST be present in the META archive (written as `archive.tar` under `stan run --context --meta`) and full archives.
   - It MUST appear in the diff whenever it changes.
 - Top-of-thread priority:
   - When scratch exists and is relevant to the current user request, treat it as the highest-priority immediate context for the thread.
@@ -852,9 +852,8 @@ diff --git a/new/path/to/file/a.ts b/new/path/to/file/a.ts
 # Inputs (Source of Truth)
 
 - Primary artifacts live under `<stanPath>/output/`:
-  - `archive.tar` — full snapshot of files to read.
-  - `archive.diff.tar` — only files changed since the previous snapshot (always written when `--archive` is used).
-  - `archive.meta.tar` — meta/system-only thread opener (only when context mode is enabled; excludes dependency state and staged payloads).
+  - `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 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,12 +945,11 @@ Dependency artifacts (workspace; gitignored):
 
 Archive outputs (under `<stanPath>/output/`):
 
-- `<stanPath>/output/archive.tar` (full)
-- `<stanPath>/output/archive.diff.tar` (diff)
-- `<stanPath>/output/archive.meta.tar` (meta; only when context mode enabled)
-  - Contains system files + dependency meta; omits dependency state always (clean slate for selections).
-  - Excludes staged payloads by omission.
-  - Never includes `dependency.map.json` (host-private; reserved denial).
+- `<stanPath>/output/archive.tar` (full by default; META when `stan run --context --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).
 
 ## Read-only staged imports (baseline rule)
 
@@ -1021,14 +1019,13 @@ Dependency expansion is intended to expand the archive beyond the baseline selec
 
 ## Meta archive behavior (thread opener)
 
-When context mode is enabled, tooling produces `<stanPath>/output/archive.meta.tar` in addition to the full and diff archives.
+In `stan run --context --meta`, tooling produces a META archive at `<stanPath>/output/archive.tar` and does not write a diff archive.
 
-The meta archive is intended for the start of a thread:
+The META archive is intended for the start of a thread:
 
-- It contains system docs + dependency meta.
-- It omits dependency state always (clean slate for selections).
+- It contains system docs + `dependency.meta.json` + `dependency.state.json` (v2 empty written by the host).
 - It excludes staged dependency payloads by omission.
-- The assistant should produce an initial `dependency.state.json` based on the prompt and then rely on full/diff archives 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

@@ -129,10 +129,9 @@ type CreateArchiveFromFilesOptions = {
 };
 
 /**
- * Creates a "meta" archive (system docs + dependency meta, plus optional
- * repo-root base files); omits dependency state (clean slate); excludes staged
- * payloads by omission and excludes `<stanPath>/system/.docs.meta.json`;
- * filesystem IO only.
+ * Creates a "meta" archive (system docs + dependency meta/state, plus optional
+ * repo-root base files); excludes staged payloads by omission and excludes
+ * `<stanPath>/system/.docs.meta.json`; filesystem IO only.
  * @module
  */
 
@@ -148,7 +147,7 @@ declare function createMetaArchive(cwd: string, stanPath: string, selection?: {
      */
     includeOutputDir?: boolean;
     /**
-     * Output file name (default: `archive.meta.tar`).
+     * Output file name (default: `archive.tar`).
      * Written to `<stanPath>/output/<fileName>`.
      */
     fileName?: string;
@@ -243,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
@@ -255,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.
@@ -268,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.
@@ -276,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.
  *
@@ -291,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;
@@ -815,6 +868,7 @@ declare const createContextArchiveDiffWithDependencyContext: (args: {
     diff: {
         baseName: string;
         updateSnapshot?: SnapshotUpdateMode;
+        snapshotFileName?: string;
         includeOutputDirInDiff?: boolean;
         onArchiveWarnings?: (text: string) => void;
     };
@@ -941,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.0"
+  "version": "0.9.2"
 }