vdelta 0.1.0 → 0.2.0

package/dist/tree-digest.js

@@ -5,19 +5,31 @@
  * excluding committed-gitignore'd paths, computed against a dedicated
  * throwaway index seeded from HEAD, with host-dependent git settings pinned.
  * Rendered as a bare 40-hex OID (documented deviation from sha256:).
+ *
+ * treeDigest() is read-only with respect to the observed repo: all git
+ * object writes (blobs from `add -A`, the tree from `write-tree`) are
+ * redirected to a throwaway GIT_OBJECT_DIRECTORY under tmpdir(), while the
+ * repo's real objects (resolved via `--git-path objects`, which also
+ * handles linked worktrees whose objects live in the common dir) are made
+ * available for reads through GIT_ALTERNATE_OBJECT_DIRECTORIES. The
+ * throwaway directory is removed again once the digest has been computed.
  */
 import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import { randomUUID } from 'node:crypto';
-import { rm } from 'node:fs/promises';
+import { mkdir, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { delimiter, join } from 'node:path';
+import { promisify } from 'node:util';
 const execFileP = promisify(execFile);
 const PIN = [
-    '-c', 'core.autocrlf=false',
-    '-c', 'core.eol=lf',
-    '-c', 'core.excludesFile=/dev/null',
-    '-c', 'advice.addEmbeddedRepo=false',
+    '-c',
+    'core.autocrlf=false',
+    '-c',
+    'core.eol=lf',
+    '-c',
+    'core.excludesFile=/dev/null',
+    '-c',
+    'advice.addEmbeddedRepo=false',
 ];
 async function git(worktree, args, env) {
     const { stdout } = await execFileP('git', [...PIN, '-C', worktree, ...args], {
@@ -28,8 +40,24 @@ async function git(worktree, args, env) {
 }
 export async function treeDigest(worktree) {
     const idx = join(tmpdir(), `vd-idx-${randomUUID()}`);
-    const idxEnv = { GIT_INDEX_FILE: idx };
+    const objDir = join(tmpdir(), `vd-obj-${randomUUID()}`);
     try {
+        await mkdir(objDir, { recursive: true });
+        const realObjects = await git(worktree, [
+            'rev-parse',
+            '--path-format=absolute',
+            '--git-path',
+            'objects',
+        ]);
+        const existingAlternates = process.env.GIT_ALTERNATE_OBJECT_DIRECTORIES;
+        const alternates = existingAlternates
+            ? `${realObjects}${delimiter}${existingAlternates}`
+            : realObjects;
+        const env = {
+            GIT_INDEX_FILE: idx,
+            GIT_OBJECT_DIRECTORY: objDir,
+            GIT_ALTERNATE_OBJECT_DIRECTORIES: alternates,
+        };
         let hasHead = true;
         try {
             await git(worktree, ['rev-parse', '--verify', '-q', 'HEAD']);
@@ -38,16 +66,17 @@ export async function treeDigest(worktree) {
             hasHead = false;
         }
         if (hasHead) {
-            await git(worktree, ['read-tree', 'HEAD'], idxEnv);
+            await git(worktree, ['read-tree', 'HEAD'], env);
         }
         else {
-            await git(worktree, ['read-tree', '--empty'], idxEnv);
+            await git(worktree, ['read-tree', '--empty'], env);
         }
-        await git(worktree, ['add', '-A'], idxEnv);
-        return await git(worktree, ['write-tree'], idxEnv);
+        await git(worktree, ['add', '-A'], env);
+        return await git(worktree, ['write-tree'], env);
     }
     finally {
         await rm(idx, { force: true });
+        await rm(objDir, { recursive: true, force: true });
     }
 }
 export async function gitHead(worktree) {
@@ -78,7 +107,11 @@ export async function gitRepoRoot(dir) {
 /** Resolve a ref to {commitSha, treeOid}; null when unresolvable. */
 export async function resolveRef(worktree, ref) {
     try {
-        const commit = await git(worktree, ['rev-parse', '--verify', `${ref}^{commit}`]);
+        const commit = await git(worktree, [
+            'rev-parse',
+            '--verify',
+            `${ref}^{commit}`,
+        ]);
         const tree = await git(worktree, ['rev-parse', '--verify', `${ref}^{tree}`]);
         return { commit, tree };
     }
@@ -89,7 +122,11 @@ export async function resolveRef(worktree, ref) {
 /** Deterministic digest material for the dirty state (status + diff vs HEAD). */
 export async function dirtyDiffMaterial(worktree) {
     try {
-        const status = await git(worktree, ['status', '--porcelain=v1', '--untracked-files=all']);
+        const status = await git(worktree, [
+            'status',
+            '--porcelain=v1',
+            '--untracked-files=all',
+        ]);
         let diff = '';
         if ((await gitHead(worktree)) !== null) {
             diff = await git(worktree, ['diff', 'HEAD', '--no-color']);

package/dist/tree-digest.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vdelta",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reference implementation of veridelta/1 — proof-carrying verification deltas for coding-agent development loops",
   "license": "MIT",
   "repository": {
@@ -35,17 +35,20 @@
     "spec"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "npm run build && npm run test",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "prepublishOnly": "npm run lint && npm run build && npm run test",
     "test": "vitest run",
     "test:unit": "vitest run --project unit",
     "test:conformance": "vitest run --project conformance",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.5.4",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.0",
     "vitest": "^4.0.0"

package/spec/veridelta-1.md

@@ -4,7 +4,7 @@
 |---|---|
 | **Status** | Draft |
 | **Schema identifier** | `veridelta/1` |
-| **Spec revision** | 0.3.0 — 2026-07-16 |
+| **Spec revision** | 0.3.1 — 2026-07-16 |
 | **License** | MIT |
 | **Reference implementation** | `vdelta` (this repository; in development) |
 
@@ -375,6 +375,37 @@ sufficient for the consumer to verify the choice (e.g.,
 comparator MUST abstain with comparability `none` (§6.3), never fall back
 silently to a weaker match.
 
+### 5.4. Near-miss disclosure
+
+When `previous-comparable` selection abstains with `baseline-missing` (§6.3)
+and the store contains at least one complete run other than the current run,
+the report MUST enrich `comparability_detail` with a `near_miss` disclosure
+identifying the nearest stored complete run and the stream-key component(s)
+(§5.1) on which it differs from the current run.
+
+Selection rule (normative, deterministic): candidates are all stored complete
+runs excluding the current run, in store insertion order; each candidate is
+scored by the number of mismatching components among the nine stream-key
+components in the canonical order `repo.identity, repo.worktree, repo.branch,
+repo.cwd, invocation.command, invocation.selector, instrument.adapter,
+instrument.adapter_version, instrument.config_digest`; the candidate with the
+fewest mismatches is selected; ties break by recency, where recency is store
+insertion order, never timestamps (§7.8).
+
+`mismatches` lists each differing component in the canonical order above with
+the candidate's recorded value and the current run's value; array-valued
+components (`invocation.command`, `invocation.selector`) are rendered as their
+elements joined by a single space. Values are drawn from stored run records,
+which are redacted before persistence (§15), so the disclosure never widens
+the exposure surface.
+
+The disclosure is informative context only: it MUST NOT alter baseline
+selection, the abstention reason, or comparability — the report still
+abstains with `baseline-missing`/`determined`, and this section does not
+weaken the stream key. Other baseline modes (`git-ref`, `explicit-run-id`,
+`previous-superset`) MUST NOT emit `near_miss`. The component-name vocabulary
+is a closed enum (§14).
+
 ## 6. Comparability
 
 ### 6.1. Levels and permitted claims
@@ -412,6 +443,9 @@ is REQUIRED whenever `comparability` is `none`:
 { "reason": "baseline-missing", "kind": "determined" }
 ```
 
+For `previous-comparable` `baseline-missing`, `comparability_detail`
+additionally carries the `near_miss` disclosure when §5.4 requires it.
+
 | `reason` | `kind` |
 |---|---|
 | `baseline-missing` | `determined` |
@@ -656,6 +690,10 @@ rendering of this schema with no independent logic.
 Additional REQUIRED-when-applicable fields:
 
 - `comparability_detail` when `comparability` is `none` (§6.3).
+- `comparability_detail.near_miss` when §5.4 applies — an object
+  `{"run_id": ..., "mismatches": [{"field": ..., "recorded": ..., "current": ...}]}`
+  where `field` is one of the nine stream-key component names (closed enum)
+  and `mismatches` is non-empty.
 - `budget_exceeded_for_safety: true` when §8's budget rule fires.
 - `masking_applied` with count and example when §7.6 dedup fired.
 - `trust.record_integrity`: `advisory | tamper-evident | trusted-environment`
@@ -920,9 +958,17 @@ Adapter roadmap for the reference implementation (informative): `vitest`
 native reporter first — agent-authored code skews heavily toward TS/JS, the
 maintainer's own repositories (the cheapest dogfood subjects) are TypeScript,
 and empirical probing confirmed the channel satisfies §3.6 with no
-stale-cache path in run mode. `pytest` native second (its richer structured
-channel is already probed and its composition pre-designed); JUnit XML third,
-for CI breadth, under the constraints above.
+stale-cache path in run mode. Playwright native reporter second, by the same
+dogfood-first criterion: maintained end-to-end suites are available as
+dogfood subjects, e2e suites are where flakiness attribution and fail-closed
+delta gating pay most, and first-class retries, per-project repetition of
+the same title, and worker parallelism exercise adapter-interface edges
+vitest does not. Commitment is contingent on an empirical probe confirming
+the structured reporter channel satisfies §3.6. `pytest` native is
+demand-driven rather than scheduled — its structured channel is already
+probed and its composition pre-designed, so the banked design does not decay
+while parked. JUnit XML is likewise demand-driven, for CI breadth, under the
+constraints above.
 
 ## 13. Conformance
 
@@ -1071,6 +1117,14 @@ None violates an invariant; each is disclosed rather than papered over.
 
 ## Revision history
 
+- **0.3.1 (2026-07-16)** — Adapter roadmap reordered (§12, informative):
+  Playwright second, by the same dogfood-first criterion that flipped the
+  first target to vitest in 0.3.0 — maintained e2e suites are available as
+  dogfood subjects, flakiness attribution and fail-closed gating pay most in
+  e2e, and retries/projects/worker parallelism exercise adapter-interface
+  edges vitest lacks — contingent on a §3.6 probe of its structured reporter
+  channel. `pytest` and JUnit XML moved to demand-driven; pytest's probe
+  results and pre-designed composition remain banked. No normative changes.
 - **0.3.0 (2026-07-16)** — First adapter target flipped to vitest after an
   empirical probe confirmed §3.6 satisfiability (core digest stable across
   rerun/line-shift/unrelated-edit, sensitive only to genuine signal; no