engineering-behavior-observatory 0.2.3 → 0.2.4

package/dist/src/artifacts.d.ts

@@ -20,14 +20,14 @@ export declare function validateArtifact(artifact: string, document: unknown): A
 export declare function validateRunManifestEvidence(artifact: string, manifest: unknown, bundleRoot: string): ArtifactValidationError[];
 export declare function validateExportManifest(artifact: string, exportManifest: unknown, containingManifest: unknown | undefined, bundleRoot?: string): ArtifactValidationError[];
 export declare function readVerifiedArtifact(artifactRoot: string, relativePath: string, expectedDigest: Digest, maxBytes?: number): Promise<Buffer>;
-export declare function inspectRetainedArtifact(artifactRoot: string, relativePath: string): Promise<{
+export declare function inspectRetainedArtifact(artifactRoot: string, relativePath: string, maxBytes?: number): Promise<{
     digest: Digest;
     sizeBytes: number;
 }>;
 export declare function writeMetadataAtomically(artifactRoot: string, relativePath: string, metadata: unknown, signal?: AbortSignal, options?: {
     overwrite?: boolean;
 }): Promise<Digest>;
-export declare function writeArtifactAtomically(artifactRoot: string, relativePath: string, content: Uint8Array, signal?: AbortSignal, options?: {
+export declare function writeArtifactAtomically(artifactRoot: string, relativePath: string, content: Uint8Array | AsyncIterable<Uint8Array>, signal?: AbortSignal, options?: {
     overwrite?: boolean;
 }): Promise<Digest>;
 export declare function writeMetadataAtomicallyIfAbsentSync(artifactRoot: string, relativePath: string, metadata: unknown, rootHandle?: BundleRootHandle, beforeDestinationPublish?: () => void, afterDestinationPublish?: () => void): {

package/dist/src/artifacts.js

@@ -852,22 +852,35 @@ export async function readVerifiedArtifact(artifactRoot, relativePath, expectedD
         await handle.close();
     }
 }
-export async function inspectRetainedArtifact(artifactRoot, relativePath) {
+export async function inspectRetainedArtifact(artifactRoot, relativePath, maxBytes) {
+    if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes < 0)) {
+        throw new Error("Artifact byte limit must be a nonnegative safe integer.");
+    }
     const { path } = await resolveExistingArtifactPath(artifactRoot, relativePath);
-    return inspectExistingPath(path, relativePath);
+    return inspectExistingPath(path, relativePath, maxBytes);
 }
 export async function writeMetadataAtomically(artifactRoot, relativePath, metadata, signal, options = {}) {
     const bytes = Buffer.from(canonicalizeMetadata(metadata));
     return writeArtifactAtomically(artifactRoot, relativePath, bytes, signal, options);
 }
 export async function writeArtifactAtomically(artifactRoot, relativePath, content, signal, options = {}) {
-    const bytes = Buffer.from(content);
+    const source = content instanceof Uint8Array ? [Buffer.from(content)] : content;
+    const hash = createHash("sha256");
+    async function* chunks() {
+        for await (const chunk of source) {
+            if (signal?.aborted)
+                throw new Error("Artifact metadata write interrupted.");
+            const bytes = Buffer.from(chunk);
+            hash.update(bytes);
+            yield bytes;
+        }
+    }
     const { parent, path } = await prepareArtifactPath(artifactRoot, relativePath);
     const temporaryPath = resolve(parent, `.${randomUUID()}.tmp`);
     let handle;
     try {
         handle = await open(temporaryPath, "wx", 0o600);
-        await handle.writeFile(bytes);
+        await handle.writeFile(chunks());
         await handle.sync();
         await handle.close();
         handle = undefined;
@@ -894,8 +907,10 @@ export async function writeArtifactAtomically(artifactRoot, relativePath, conten
         await handle?.close();
         await rm(temporaryPath, { force: true });
     }
-    const digest = digestBytes(bytes);
-    await readVerifiedArtifact(artifactRoot, relativePath, digest);
+    const digest = { algorithm: "sha256", value: hash.digest("hex") };
+    const inspected = await inspectRetainedArtifact(artifactRoot, relativePath);
+    if (inspected.digest.value !== digest.value)
+        throw new Error(`Artifact "${relativePath}" digest does not match its source reference.`);
     return digest;
 }
 export function writeMetadataAtomicallyIfAbsentSync(artifactRoot, relativePath, metadata, rootHandle, beforeDestinationPublish, afterDestinationPublish) {
@@ -1270,7 +1285,7 @@ function prepareArtifactPathSync(artifactRoot, relativePath) {
 function digestExistingPath(path, relativePath) {
     return inspectExistingPath(path, relativePath).digest;
 }
-function inspectExistingPath(path, relativePath) {
+function inspectExistingPath(path, relativePath, maxBytes) {
     const descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
     try {
         let opened = fstatSync(descriptor);
@@ -1283,6 +1298,9 @@ function inspectExistingPath(path, relativePath) {
             || !Number.isSafeInteger(opened.size) || opened.size < 0) {
             throw new Error(`Artifact path "${relativePath}" is not an isolated regular file.`);
         }
+        if (maxBytes !== undefined && opened.size > maxBytes) {
+            throw new Error(`Artifact "${relativePath}" exceeds the qualification byte limit of ${maxBytes}.`);
+        }
         const hash = createHash("sha256");
         const chunk = Buffer.allocUnsafe(64 * 1024);
         for (let offset = 0; offset < opened.size;) {

package/dist/src/run-bundles.js

@@ -1,9 +1,12 @@
 import { execFile, spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
 import { cp, lstat, mkdir, mkdtemp, readdir, rm, rmdir, utimes, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { promisify } from "node:util";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { HOOK_EVENTS } from "@anthropic-ai/claude-agent-sdk";
 import { assertNoDuplicateJsonKeys, assertUniqueArtifactIdentities, canonicalizeMetadata, inspectRetainedArtifact, readVerifiedArtifact, validateArtifact, validateExportManifest, validateRunManifestEvidence, writeArtifactAtomically, writeMetadataAtomically, } from "./artifacts.js";
 import { isSafeArtifactRelativePath } from "./contracts.js";
@@ -11,7 +14,7 @@ import { digestWorkspace, digestWorkspaceTree } from "./verifiers.js";
 import { readBoundedFile } from "./scheduler.js";
 const execFileAsync = promisify(execFile);
 const MAX_WORKSPACE_PATCH_BYTES = 64 * 1024 * 1024;
-const MAX_WORKSPACE_SNAPSHOT_BYTES = 128 * 1024 * 1024;
+const MAX_WORKSPACE_SNAPSHOT_BYTES = 1024 * 1024 * 1024;
 const MAX_QUALIFICATION_ARTIFACT_BYTES = 64 * 1024 * 1024;
 const QUALIFICATION_DIMENSION_RANK = { qualified: 0, unsupported: 1, gap: 2, unqualified: 3 };
 const PINNED_HOOK_EVENTS = new Set(HOOK_EVENTS);
@@ -151,11 +154,17 @@ export class RunBundleAssembler {
                 throw new Error("Final workspace metadata changed while its outcome was being captured.");
             }
             const format = patch === undefined ? "snapshot" : "patch";
-            const content = patch ?? await workspaceSnapshot(capturedPath, treeDigest);
             const relativePath = format === "patch"
                 ? options.relativePath ?? "workspace.patch"
                 : options.snapshotRelativePath ?? "workspace.tar.gz";
-            await writeArtifactAtomically(this.bundleRoot, relativePath, content, undefined, { overwrite: false });
+            if (patch !== undefined) {
+                await writeArtifactAtomically(this.bundleRoot, relativePath, patch, undefined, { overwrite: false });
+            }
+            else {
+                await workspaceSnapshot(capturedPath, treeDigest, async (snapshotPath) => {
+                    await writeArtifactAtomically(this.bundleRoot, relativePath, createReadStream(snapshotPath), undefined, { overwrite: false });
+                });
+            }
             const descriptor = await this.registerArtifact({
                 id: options.id ?? "workspace",
                 source: options.source ?? `workspace-${format}`,
@@ -312,9 +321,15 @@ export async function qualifyRunBundle(bundleRoot, options = {}) {
         const state = { descriptor, valid: true };
         states.set(descriptor.id, state);
         try {
-            const bytes = await readVerifiedArtifact(bundleRoot, descriptor.relativePath, digestValue(descriptor.digest), descriptor.kind === "workspace" && descriptor.mediaType === "application/gzip"
-                ? MAX_WORKSPACE_SNAPSHOT_BYTES
-                : MAX_QUALIFICATION_ARTIFACT_BYTES);
+            if (descriptor.kind === "workspace" && descriptor.mediaType === "application/gzip") {
+                // Opaque snapshots need streaming integrity checks, not a whole-archive buffer.
+                const inspected = await inspectRetainedArtifact(bundleRoot, descriptor.relativePath, MAX_WORKSPACE_SNAPSHOT_BYTES);
+                if (inspected.sizeBytes !== descriptor.sizeBytes || digestString(inspected.digest.value) !== descriptor.digest) {
+                    throw new Error("Workspace snapshot size or digest does not match its descriptor.");
+                }
+                continue;
+            }
+            const bytes = await readVerifiedArtifact(bundleRoot, descriptor.relativePath, digestValue(descriptor.digest), MAX_QUALIFICATION_ARTIFACT_BYTES);
             if (descriptor.mediaType === "application/x-ndjson") {
                 const summary = parseNativeJsonl(bytes);
                 state.hookNames = summary.hookNames;
@@ -966,7 +981,7 @@ async function workspacePatch(startPath, finalPath, finalTreeDigest) {
         await rm(temporaryRoot, { recursive: true, force: true });
     }
 }
-async function workspaceSnapshot(finalPath, finalTreeDigest) {
+async function workspaceSnapshot(finalPath, finalTreeDigest, use) {
     const temporaryRoot = await mkdtemp(join(tmpdir(), "ebo-workspace-snapshot-"));
     const snapshotPath = join(temporaryRoot, "workspace.tar.gz");
     const snapshotParent = join(temporaryRoot, "source");
@@ -975,18 +990,33 @@ async function workspaceSnapshot(finalPath, finalTreeDigest) {
     try {
         await mkdir(snapshotParent);
         await cp(finalPath, snapshotRoot, { recursive: true, preserveTimestamps: true, force: false });
-        const { stdout } = await execFileAsync(TAR_COMMAND, ["-czf", "-", "-C", snapshotParent, "workspace"], {
-            encoding: "buffer",
-            maxBuffer: MAX_WORKSPACE_SNAPSHOT_BYTES,
+        const child = spawn(TAR_COMMAND, ["-czf", "-", "-C", snapshotParent, "workspace"], { stdio: ["ignore", "pipe", "pipe"] });
+        let stderr = "";
+        child.stderr.on("data", (chunk) => { stderr = (stderr + chunk.toString("utf8")).slice(-8192); });
+        const exited = new Promise((resolveExit, reject) => {
+            child.once("error", reject);
+            child.once("close", (code) => code === 0 ? resolveExit() : reject(new Error(`Workspace snapshot tar failed (${code}): ${stderr.trim()}`)));
         });
-        const snapshot = Buffer.from(stdout);
-        await writeFile(snapshotPath, snapshot, { flag: "wx", mode: 0o600 });
+        let size = 0;
+        const limit = new Transform({ transform(chunk, _encoding, callback) {
+                size += chunk.length;
+                callback(size > MAX_WORKSPACE_SNAPSHOT_BYTES ? new Error("Workspace snapshot exceeds the 1 GiB compressed byte limit.") : null, chunk);
+            } });
+        const streamed = pipeline(child.stdout, limit, createWriteStream(snapshotPath, { flags: "wx", mode: 0o600 }));
+        try {
+            await Promise.all([exited, streamed]);
+        }
+        finally {
+            if (child.exitCode === null)
+                child.kill("SIGKILL");
+            await Promise.allSettled([exited, streamed]);
+        }
         await mkdir(extracted, { mode: 0o700 });
         await execFileAsync(TAR_COMMAND, ["-xzpf", snapshotPath, "-C", extracted]);
         if (await digestWorkspaceTree(join(extracted, "workspace")) !== finalTreeDigest) {
             throw new Error("Bounded workspace snapshot cannot reproduce the final workspace tree.");
         }
-        return snapshot;
+        await use(snapshotPath);
     }
     finally {
         await rm(temporaryRoot, { recursive: true, force: true });

package/docs/guides/evidence-and-sharing.md

@@ -46,6 +46,15 @@ missing-evidence entries. Inspect the detail before retrying capture against a
 retained workspace. A later successful capture is recovery evidence; it does
 not change the original attempt's recorded failure.
 
+Workspace capture tries a patch up to 64 MiB, then falls back to a snapshot
+when the patch is too large or cannot reproduce the tree. Snapshots stream to
+disk with a 1 GiB compressed limit and are extracted to verify the tree digest
+before publication. Snapshot qualification also checks integrity without loading
+the archive into memory. Exceeding the limit leaves explicit missing evidence
+and retains the workspace; it never truncates the archive. These capture limits
+are separate from portable-export limits. Configure known cache-directory
+exclusions before a study rather than dropping files from an existing attempt.
+
 Use a new output destination for derived records and reruns. Do not edit a
 native bundle to make a validator accept it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-behavior-observatory",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Capture engineering-agent trajectories, evaluate behavior, and inspect cited evidence across harnesses.",
   "license": "Apache-2.0",
   "repository": {
@@ -47,6 +47,7 @@
     "release/0.2.1/",
     "release/0.2.2/",
     "release/0.2.3/",
+    "release/0.2.4/",
     "schemas/",
     "scripts/atlas-grafana.sh"
   ],

package/release/0.2.4/KNOWN_LIMITATIONS.md

@@ -0,0 +1,16 @@
+# v0.2.4 known limitations
+
+The [v0.2.3 limitations](../0.2.3/KNOWN_LIMITATIONS.md) continue to apply.
+
+- Snapshots remain bounded to 1 GiB compressed. Temporary source and extracted
+  copies also require free disk space; large cache trees increase capture time.
+- Known cache exclusions must be declared before a study. Capture does not
+  silently omit additional files to fit a limit.
+- Opaque snapshots remain restricted evidence; larger capture support does
+  not make them portable sanitized exports.
+- Full-parallel testing exposed intermittent interruption/cleanup failures.
+  Release acceptance runs tests serially, as in earlier releases.
+- npm audit reports three dependency findings (two moderate, one high) through
+  the pinned Cursor SDK's connect-node/undici dependency chain. npm reports no
+  available automatic fix for this dependency graph. This patch leaves those
+  dependencies unchanged; passing acceptance is not a clean security audit.

package/release/0.2.4/README.md

@@ -0,0 +1,23 @@
+# v0.2.4: Stream large workspace snapshots
+
+Workspace snapshot capture no longer buffers the compressed archive in child
+process stdout. Archives stream to disk, pass extraction and tree-digest checks,
+and publish atomically. Qualification verifies snapshot integrity in chunks.
+
+The compressed snapshot limit increases from 128 MiB to 1 GiB. Output above
+that limit fails explicitly and retains partial evidence. The 64 MiB patch
+limit, capture exclusions, archive format, and portable-export policy are
+unchanged. No runtime pins or dependencies change.
+
+## Verification
+
+Regression tests cover a 129 MiB incompressible snapshot, streamed-write failure
+cleanup, no-clobber publication, and bounded integrity checks. A retained real
+workspace that failed on v0.2.3 was captured separately as a 605,143,040-byte
+snapshot, with its extracted tree digest verified. Original evidence was not
+rewritten.
+
+Run `npm ci` and `npm run acceptance` on Node 24.19.0 for the full suite,
+documentation and package checks, and two byte-identical package builds.
+See [known limitations](KNOWN_LIMITATIONS.md) and the
+[reproducibility manifest](reproducibility.json).

package/release/0.2.4/reproducibility.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": "ebo.release-reproducibility/v1",
+  "release": {
+    "name": "engineering-behavior-observatory",
+    "version": "0.2.4"
+  },
+  "runtime": {
+    "node": "24.19.0",
+    "claudeAgentSdk": "0.3.258",
+    "openhandsAgentServer": "1.46.0",
+    "deepseekClient": "0.1.1-rc.2",
+    "deepseekProtocol": "0.1.1-rc.2",
+    "deepseekRuntime": "0.1.1-rc.2",
+    "codexAppServer": "0.153.4",
+    "grafana": "13.2.0",
+    "grafanaInfinity": "4.0.0",
+    "piSdk": "0.85.1",
+    "cursorSdk": "1.0.31"
+  },
+  "commands": [
+    "npm ci",
+    "npm run acceptance"
+  ],
+  "fixtureCoverage": {
+    "agent-sdk": "frozen queue entry through qualified capture, approved export, normalization, configurable judging, review, aggregation, and Atlas",
+    "openhands-agent-server": "pinned REST/WebSocket stream-final reconciliation, workspace/outcome evidence, partial capture, and retained evaluation",
+    "deepseek-harness": "official-client JSON-RPC composition, receipt-to-idle completion, stderr, interruption, shutdown, swaps, and retained evaluation",
+    "codex-app-server": "owned stdio lifecycle, full history, OTLP, interruption/failure, export, and retained evaluation; configurable workspace-write networking with explicit offline queue propagation",
+    "acceptance-cases": "seeded ordering, secret scanning, partial attempts, native references, abstention, disputes, denominators, and unsupported comparisons",
+    "pi-sdk": "frozen queue, passive hooks, durable session, partial cleanup, export, retained normalization and evaluation",
+    "cursor-sdk": "frozen queue, official store, callbacks/history, bounded cancellation, export, retained normalization and evaluation",
+    "workspace-capture": "streamed snapshot capture, atomic publication and qualification beyond 128 MiB; bounded 1 GiB compressed output; retained error and partial evidence"
+  },
+  "determinism": {
+    "stable": [
+      "task, run, attempt, event, assertion, aggregate, and Atlas case identities",
+      "fixture, native-reference, normalized-dataset, source/cohort, archive, and package digests",
+      "seeded queue and review-sample ordering"
+    ],
+    "excluded": [
+      "native and EBO observation timestamps",
+      "lifecycle start/finish timestamps",
+      "provider timing and usage",
+      "temporary workspace and output paths"
+    ]
+  },
+  "fixtures": {
+    "tests/fixtures/task-packet.valid.v1.json": "ac2ef1043c0cc16bf4c21d05c1dc880ca1b4b8cc2f9ea7653328e91f0b0e2681",
+    "test/fixtures/agent-sdk-normalizer/complete.input.json": "7285dee088517e5de38ceda84fc7c58d9303949c7448ab3b5e10a5a2d2ebdfe3",
+    "test/fixtures/agent-sdk-normalizer/complete.expected.jsonl": "d32fa3a013bc179f1673f7e1a89b8a721bb8ddaf63eba5bc8a3f14f1cc148ed8",
+    "contracts/openhands-agent-server-v1.44.1.json": "e7a07977688a0703b15751a8a1ab17f29be45f9fdf438017e0dbcbc49cca37b0",
+    "contracts/openhands-agent-server-v1.46.0.json": "455cdddd2c206cb2f20245c2189b92e773657ec14d651236baa532b2dbadeb28",
+    "test/fixtures/openhands/v1.44.1/streamed-events.json": "d751083ba2ef94c9865117db481cc2f4933772bbbbb6b9fcf60571563715c1ea",
+    "test/fixtures/openhands/v1.44.1/final-events.json": "551db9904e860004d604c923692b5c5d3aaee966220492214c60003d2df415b6",
+    "test/fixtures/deepseek/golden-success.json": "f3867d38169bf0e28f64aba1dd60553f21cf07f41f81b4bad48261e49fa3ca88",
+    "test/fixtures/deepseek/golden-interrupted.json": "79e1f8404df1ee3b562d0bdbc0b2ee712ffc6d5774992b92970814ea815677b7",
+    "test/fixtures/deepseek/compositions/minimal/composition.json": "72fe4368e105f1bad82b7fdf8380e92c9fa689d8985f6ab91f534f0baf3eda02",
+    "contracts/codex-app-server-0.153.4/manifest.json": "e62281ff5e5d1cc71d07763b85e997ccc9ddbad9aa82a469da4181ee4b1890a8",
+    "test/fixtures/codex/legacy-0.150.1.dataset.json": "f71906b009e546afbf3b4e79396f223181382f3b3d8795e9cfcd032398a9d6bf",
+    "test/fixtures/behavior-assertions/abstained.json": "7f1962864f664c794925a67d93074e7b150af0f57c58041a81e062990d641197",
+    "test/fixtures/behavior-assertions/disputed.review.json": "450d3d9efe7feefaf7500b3ad20ab2803b412c7e53b91763125e15a83be87981",
+    "test/fixtures/comparison/exact.json": "cafa68e94b8d50dc308ddcfc2e73aa139c828b4ecd1e1c762bbc51bf1b44501e",
+    "test/fixtures/structural-observations/golden.json": "bad71a3a93524b76c0a2fdbb58e98e1e65be46cae14acf18ac89d9ba76e03e8a",
+    "test/atlas-fixture.ts": "9f03ce9cbcd0e5d3e3a5916866554ceb1c21f1c8712e58529499c1ea499f048d",
+    "test/pi.test.ts": "a00997c5617ca178e19b25b0d483cbdce8ce7c306d4c871557945b31a2e657cf",
+    "test/cursor-sdk.test.ts": "753094f127b11dc392ec2244c9edddabec27aa94347bb6159a292129ed2a2822",
+    "examples/cursor-sdk/README.md": "a2cf481123e7f3deb1c5a682ba208a775c3f91c35e1a6c1a428c517c79692618",
+    "examples/cursor-sdk/capture-profile.json": "d1a5787875daf5523b3783f259b891c256a904cbb10279d5be214af846305a2d",
+    "examples/cursor-sdk/harness.json": "2f1da6f2b17258d0ee59431f687696901ce3692589175d182f3a4bbe8dd4d689",
+    "examples/cursor-sdk/model.json": "ad8f31ff5d2387c02d79226679022358afafc61ba5dda73040e3f754530a230a",
+    "examples/cursor-sdk/native-limits.json": "40fe451f56b0863e79b42f5c85defbce678e1dc90dd248d15c430db176d71511",
+    "examples/cursor-sdk/native-tool-policy.json": "0fef98b36cd39de82914c5b068022c1335dadda24b7d6e7df398b2430e6a16e0"
+  }
+}

package/release/README.md

@@ -5,6 +5,7 @@ For downloads and published artifacts, see
 
 | Version | Changes and verification | Support boundary |
 | :--- | :--- | :--- |
+| [0.2.4](0.2.4/README.md) | Stream workspace snapshots and integrity checks; support archives up to 1 GiB | [Known limitations](0.2.4/KNOWN_LIMITATIONS.md) |
 | [0.2.3](0.2.3/README.md) | Retain workspace capture errors in partial-bundle reports | [Known limitations](0.2.3/KNOWN_LIMITATIONS.md) |
 | [0.2.2](0.2.2/README.md) | Configurable Codex tool networking, enabled by default for workspace-write | [Known limitations](0.2.2/KNOWN_LIMITATIONS.md) |
 | [0.2.1](0.2.1/README.md) | Documentation redesign, Apache-2.0, and npm distribution setup | [Known limitations](0.2.1/KNOWN_LIMITATIONS.md) |