engineering-behavior-observatory 0.2.1

package/docs/reference/contracts.md

@@ -0,0 +1,222 @@
+# Task-packet and experiment contracts
+
+The post-capture uniform event and adapter boundary is documented separately in
+[uniform-events.md](../evaluation/uniform-events.md). Its schemas consume capture-qualified
+native evidence; they are not task-authorship or experiment inputs.
+
+EBO accepts externally authored task packets and experiment configurations as
+versioned JSON documents. The schemas are the contract; this repository does
+not contain an evaluation corpus or a fixed operating matrix.
+
+## Task packets
+
+`schemas/task-packet.v1.schema.json` divides a packet into two surfaces:
+
+- `agentInput` is the only surface a workspace materializer may use. It holds
+  the public prompt, a digest-verified sanitized TAR+gzip v1 archive with
+  compressed-byte, expanded-byte, and member-count limits, and an explicit
+  workspace-relative allowlist. A materializer verifies the archive digest and
+  copies only entries selected by `includePaths`; it must not materialize a raw
+  repository checkout or an entry outside that allowlist.
+- Its archive locator is a secret-free, bundle-relative logical path. URLs,
+  absolute local paths, credentials, and path traversal are invalid there. Its
+  resolver rejects links and paths that leave the real task-bundle root.
+  Include paths are canonical POSIX logical paths only; leading slashes, trailing
+  slashes, backslashes,
+  drive letters, UNC paths, and traversal forms are invalid.
+  Common framework filenames may use brackets, parentheses, `+`, and `@`;
+  spaces, colons, wildcard characters, and shell metacharacters remain invalid.
+- `verified-archive-literal-paths-v1` resolves each literal from the sanitized
+  archive root. A file includes that file; a directory includes its complete
+  descendant tree. Wildcards are intentionally unsupported.
+- `verified-archive-literal-paths-no-links-v1` adds the required v1 link rule:
+  enumerate every selected entry and selected directory descendant before copy,
+  then reject every non-file/non-directory entry. Links are never copied or dereferenced. Every
+  selected member name must be a canonical root-relative logical path before
+  joining either archive or workspace roots.
+- Archive membership and allowlist selection use exact canonical POSIX names.
+  Case folding is used only to reject destination collisions across filesystems.
+- `assessmentMode` is explicit. `observational` packets are the primary
+  open-ended task form and omit `restricted` entirely. `verified` packets use
+  `restricted` only for digest-addressed reference-solution and verifier
+  references; the packet cannot embed their contents.
+
+The packet records repository provenance, a controlled perturbation, admission
+review status, sharing classification, and SHA-256 digests for every frozen
+component. Every digest has one authority: the safe fixture source, controlled
+perturbation artifact, and restricted component references carry their own. The schema
+does not claim a separate agent-input digest without defining its canonical
+bytes; admission-freeze tooling owns the whole-packet identity.
+
+`proposed` packets explicitly set `admission.review` to `null`. `admitted` and
+`rejected` packets require a reviewer, RFC 3339 `date-time` evidence, and the
+restricted review-record reference. Repository provenance is a credential-free
+HTTPS repository URI, optionally on an explicit port, plus a full immutable Git
+object ID. Branches and tags are not accepted. A verifier is required only for `verified`
+packets; `referenceSolution.status` may be `not-provided` or `unsupported` for
+verifier-only work. Controlled perturbation
+content is either an external, digest-addressed artifact or an explicit
+`not-applied`/`unsupported` state; EBO does not prescribe a task-authoring
+taxonomy.
+
+Before scheduling, EBO requires an admitted packet's review time to be a valid
+RFC 3339 calendar timestamp and its review record. Verified packets additionally
+require provided reference-solution and verifier bytes to match their pinned digests. The review record binds the
+canonical pre-admission packet digest; the admitted packet can then hash its
+review-record reference without requiring a circular digest. Each declared
+materialization literal must select at least one verified archive file or
+directory tree. A referenced controlled perturbation also hashes to its pinned
+digest before scheduling; explicit unavailable states remain distinct from a
+referenced artifact that fails to resolve.
+
+### Admission and freeze
+
+Task-packet tooling consumes an externally authored packet; it does not create
+tasks or make a human review decision. `validate` checks the packet schema,
+parses each declared TAR+gzip fixture, verifies its declared size/member/link
+limits and literal allowlist, and resolves every declared perturbation,
+mode-appropriate reference/verifier, and review-record digest. `admit` additionally
+requires the recorded admission status to be `admitted` and a complete human
+review.
+
+`freeze` writes a sibling
+[`ebo.task-packet-freeze/v1`](../../schemas/task-packet-freeze.v1.schema.json)
+record. It records the assessment mode and stable SHA-256 digests for the
+prompt, fixture, optional reference solution/verifier, review record,
+controlled perturbation, and canonical packet. The review record binds the canonical packet content with its
+`admission` field omitted, using its `preAdmissionDigest` field and avoiding a
+circular reference. The aggregate digest is derived from those identities, the
+packet locator, and the recorded `frozenAt` timestamp. Repeating a freeze for
+unchanged content retains the first published record and its timestamp.
+An existing freeze is never silently replaced after a component changes.
+
+`status` compares the current packet and resolved bytes with the freeze record
+and reports the named mismatching component before a later materializer or
+scheduler can consume it. The model-visible projection is only `agentInput`;
+verified-task reference solutions/verifier bytes and all review records remain restricted.
+
+## Workspace materialization
+
+`materializeWorkspace` accepts an admitted packet with a `frozen` status and
+creates an attempt-identified directory outside the task bundle. It verifies
+the digest-pinned TAR+gzip source, copies only the declared literal allowlist,
+rejects links, special entries, traversal, and a selected `restricted/`
+subtree, then normalizes private modes and timestamps before calculating the
+`workspaceFingerprint` used for outcome binding and, when present, verification. The result's `startingDigest` is
+the declared fixture digest; `workspaceDigest` is the normalized tree
+fingerprint. Attempt roots and non-executable files use `0700` and `0600`;
+executable archive or setup files retain the owner execute bit.
+
+Setup callbacks receive the disposable workspace path and an invocation-owned
+`{ spawn }` context. Child processes that setup needs to create must use that
+context: each child is placed in a private process group and its group is
+terminated before the fingerprint is calculated. This prevents cleanup from
+mistaking unrelated coordinator processes for setup descendants. A setup step
+must settle all in-process writes (including timers and promises) and must not
+leave ambient child processes behind before returning; arbitrary filesystem
+closures cannot be revoked without a sandbox. Stronger process isolation can
+still be supplied by the evaluation environment. Call
+`cleanupWorkspace(result, "success")` (or `result.cleanup("success")`) after a
+successful attempt. A failed setup returns a failed lifecycle result;
+`retainOnFailure: true` keeps its attempt path for inspection after normalizing
+an owned tree to private modes, while the default removes it. Identity changes,
+links, special entries, and paths that cannot be safely normalized are never
+retained. Failure retention never changes the model-visible input surface or
+the frozen packet.
+
+## Experiments
+
+`schemas/experiment.v1.schema.json` treats task, model, and harness sets;
+trial count; ordering seed; coordinator wall-clock budget; and capture profile
+as data. Each condition set is an ID-keyed map, so one identity can expand to
+only one matrix condition. Every referenced configuration has a SHA-256 digest.
+Each harness condition separately names source-specific native-limits and
+native-tool-policy configurations; EBO does not define a shared turn count or
+tool namespace.
+
+Every experiment configuration reference is a portable bundle-relative logical
+path, resolved from the experiment bundle root rather than the current working
+directory. The resolver checks each component without following symbolic links
+and rejects a path that leaves the real bundle root. URLs, absolute paths,
+traversal, aliases such as `./`, and backslashes are invalid. A
+`permuted` order also names a digest-pinned permutation-algorithm reference;
+that versioned artifact defines how the supplied seed orders matrix cells. Each
+resolved model, harness, native-limit, native-tool-policy, capture-profile, and
+permutation artifact must hash to its pinned digest before scheduling.
+
+`declared` ordering carries explicit task, model, and harness ID lists. Matrix
+compilers use those lists, never object-property enumeration, and reject a list
+unless it is an exact permutation of its condition-set IDs. Before expansion, a
+compiler resolves every task packet, checks the reference digest, and requires
+`admission.status` to be `admitted`. Capture profiles use the same digest-pinned
+configuration-reference shape as other immutable experiment inputs.
+
+For declared matrices, traversal is task outermost, then model, then harness,
+with one-based trial replicas innermost. The compiler rejects duplicate task
+packet digests across task IDs before expansion. The declared cell iterator is
+lazy, so externally supplied trial counts do not allocate a full matrix.
+
+The fixtures include a generic 18-cell matrix and a differently shaped matrix
+to show that no study dimensions are built into the contract. Parsed numeric
+controls are limited to JavaScript safe integers.
+
+## Run queues
+
+`compileRunQueue` expands an experiment into a persisted
+`ebo.run-queue/v1` document. Every entry contains the task-packet freeze
+identity, digest-pinned model and harness configuration references, and a
+one-based trial identity; the queue also retains the selected capture-profile
+reference and coordinator budget. A scheduling digest covers those controls,
+the matrix, seed, and ordering policy; run IDs include that digest so
+standalone consumers reject mutations to any persisted scheduling input. When
+the API is used without a bundle root, each admitted task resolution must carry
+the complete schema-valid freeze record that supplied task identities are
+checked against. Freeze locators are distinct from every packet/configuration
+artifact path and from each other; persisted custom locators are reused when
+queues are revalidated without a bundle root.
+
+The compiler supports sequential (`declared` is retained as its legacy name),
+seeded-shuffle (`permuted` is retained as its legacy name), and balanced
+interleaving. Interleaving round-robins the selected dimension (model by
+default) and preserves every cell exactly once, including matrices whose
+groups have different sizes. Configuration references are resolved before
+compilation, and every task packet must have a matching, admitted freeze
+record. A seeded-shuffle with a permutation reference reads that verified
+artifact and currently accepts the declared `fisher-yates-v1` algorithm;
+unknown algorithm definitions fail closed. The normalized queue records the
+resolved algorithm name, so experiment-only validation remains reproducible;
+passing a bundle root additionally rechecks the pinned artifact. Queue writes
+use the existing atomic artifact writer and do not execute work or coordinate
+across machines.
+
+The CLI exposes `ebo matrix compile <experiment.json> <bundle-root>
+<queue.json> [--freeze-locator <task-id>=<path>]`, `ebo queue inspect
+<queue.json>`, and `ebo queue validate
+<queue.json> [experiment.json] [--bundle-root <bundle-root>]`. Supplying the
+bundle root lets queue validation recheck each freeze and pinned algorithm
+artifact. The 18-cell fixture is only a generality test;
+the compiler has no fixed task, model, harness, or trial count, subject to the
+bounded 100,000-entry local queue limit; larger matrices require a future
+streaming queue implementation.
+
+## Agent SDK run configuration
+
+`ebo.agent-sdk-config/v1` is the single discriminated contract behind the five
+digest-pinned configuration artifacts a queue entry already references. The
+`kind` values are `model`, `harness`, `native-limits`, `native-tool-policy`,
+and `capture-profile`; `ebo agent-sdk run` resolves each reference through the
+bundle resolver and validates the record before launching the Agent SDK. The
+model record's `model` must equal the queue entry's model ID, the harness
+adapter must be `claude-agent-sdk`, tool lists are arrays of unique nonempty
+Agent SDK tool names, and `bypassPermissions` is accepted only with an explicit
+`allowDangerouslySkipPermissions: true`. Duplicate JSON keys, unknown fields,
+unsafe numbers, wrong kinds, digest mismatches, and malformed UTF-8 or JSON
+fail before an attempt starts. Credentials and environment overrides are never
+read from these files; authentication stays in the process environment, and
+telemetry content flags default to false. A configured telemetry endpoint
+without a receipt checker remains explicit `not-checked` receipt evidence. The
+full runner specification is
+[agent-sdk-operational-runner.md](agent-sdk-operational-runner.md).
+
+Unknown schema versions and sharing classifications are invalid. Consumers must
+validate a document before materializing a workspace or scheduling a run.

package/docs/reference/run-bundle-contract.md

@@ -0,0 +1,354 @@
+# Run-bundle contract
+
+Run bundles retain the evidence needed to inspect one attempt without copying
+native harness payloads into a common event model. This contract is versioned
+as [`schemas/run-bundles/v1.json`](../../schemas/run-bundles/v1.json).
+
+## Bundle layout
+
+```text
+run-bundle/
+  manifest.json
+  session.jsonl
+  hooks.jsonl
+  telemetry/
+  workspace.patch
+  verifier.json       # verified tasks only
+  capture-report.json
+  export/manifest.json
+```
+
+`manifest.json` is the run-manifest schema root. Its evidence descriptors are
+the portable index: each gives an artifact ID, source, authority, media type,
+SHA-256 digest, byte size, sharing class, bundle-relative path, and native type
+and identity when the source provides them. Native content stays in the
+referenced file. Artifact IDs are unique within a bundle, and every bundle
+retains exactly one capture-report descriptor.
+
+For TypeScript Agent SDK runs, `openClaudeAgentSdkHookCapture` creates the
+no-clobber `hooks.jsonl` sink. Each source-specific record retains the complete
+typed callback input, callback time, empty neutral callback output, abort-signal
+state, and only the session, prompt, tool-use, agent, transcript, and working
+directory identities the callback exposed. Because the native payload can
+contain prompts, tool inputs, and local paths, the resulting artifact is
+restricted evidence; later export policy must not treat the source file as a
+sanitized derivative.
+
+`hooks.jsonl` is authoritative for callback occurrence. Optional detailed-beta
+hook spans are a separate timing capability and are not required to infer or
+confirm an occurrence. If a hook append fails, the executor returns the neutral
+empty hook output, keeps the agent operation running, and retains a bounded
+capture warning in the attempt evidence.
+
+All paths are bundle-relative. The schema rejects absolute and parent-traversal
+paths; the shared artifact utilities will also resolve symlinks and verify
+digests before use. Each retained path appears exactly once under a
+case-folded portable identity. A sanitized
+partner or public artifact therefore has its own retained path, and source bytes
+cannot masquerade as another evidence class.
+
+## Evidence authority
+
+| Authority | Source of record | It can answer |
+| --- | --- | --- |
+| `semantic` | Native session and hook artifacts | What the agent and harness exchanged or observed |
+| `timing-resource` | Native telemetry | Timing, tokens, cost, and resource observations |
+| `outcome` | Workspace and optional verified-task artifacts | What changed and, only for verified tasks, whether executable assertions passed |
+| `capture` | Capture report | Which evidence is available, missing, or unsupported |
+| `export` | Export manifest | Which approved artifacts were prepared for sharing |
+
+The contract does not describe a uniform event ontology or attach semantic
+quality labels. Source-specific records remain authoritative until a later,
+capture-qualified normalization step.
+
+Evidence kind and authority are fixed pairs: sessions and hooks are semantic;
+telemetry is timing-resource; workspace and verifier records are outcome; the
+capture report is capture; and the export manifest is export.
+
+## Attempt and terminal semantics
+
+A run identifies the declared task/model/harness condition. An attempt is one
+execution of that run; retries get a new attempt ID and must point at `retryOf`.
+`retryOf` cannot name the attempt itself. No attempt replaces prior evidence.
+When a run declares a native session ID, it retains at least one session
+reference naming that same native session, with at least one parsed native
+record.
+The same rule applies to a declared native trace ID and retained telemetry
+evidence. Runtime components are unique by source, name, and version.
+
+`runtime` is a non-empty list of source-specific components, each with source,
+name, and version. One component's source or name and version represents the
+declared harness. An Agent SDK run can record SDK and CLI components; an Agent
+Server run can record only its server component. No integration invents an
+absent SDK or CLI identity.
+
+`terminal` separates these conditions:
+
+| Terminal state | Failure class | Stop reason |
+| --- | --- | --- |
+| `completed` | `none` | `none` |
+| `failed` | `infrastructure` or `task` | `none` |
+| `stopped` | `none` | `budget` or `policy` |
+| `interrupted` | `infrastructure` | `none` |
+
+Every run declares `assessmentMode`. `observational` is the primary mode for
+open-ended engineering work: a `completed` terminal means execution ended
+normally with retained workspace evidence, not that the task was correct or
+stakeholder-approved. It has no verifier artifact. `verified` preserves the
+existing verifier-backed completion and task-failure semantics.
+
+Capture incompleteness is not a task or infrastructure failure class. It is a
+capture-report qualification with an explicit missing-evidence reason.
+
+## Qualification
+
+`capture-report/v1` records `semantic`, `timingResource`, and `outcome`
+capabilities separately. A `qualified` report requires available semantic and
+outcome evidence and checked timing-resource evidence. For observational runs,
+workspace evidence satisfies the outcome capability; verified runs also require
+their verifier evidence. Missing optional beta spans are recorded as
+`optional-beta-unavailable` affecting `timing-resource`; they never assert that
+semantic evidence is missing. Every unavailable capability has an explicit
+missing-evidence entry; optional-beta-unavailable affects timing-resource only.
+An available capability requires an indexed artifact with that authority. The
+embedded capture report must also name the containing bundle. An `incomplete`
+report remains a valid retained partial bundle but is not capture-qualified.
+Missing-evidence effects cannot contradict a capability reported as available.
+`unsupported` and `not-checked` reasons each match their corresponding
+capability status.
+
+An artifact may retain `sharingClass: unknown` when capture cannot classify it.
+Exports fail closed: unknown artifacts and unknown export classes are never
+ready or exported.
+
+The final capture report for a direct Agent SDK attempt also retains the exact
+SDK/CLI capability profile, effective model/tool/permission/budget
+configuration, and expected hook set used for qualification. Its
+`structuralQualification` field preserves the resulting dimension statuses and
+reason codes. These are capture facts, not behavioral judgments, and remain
+internal until the export policy produces an approved derivative.
+
+Real package-manager workspaces may declare a bounded outcome projection:
+directory names such as `node_modules` and `coverage`, source `.gitignore`
+rules, and empty-directory omission. EBO copies the final workspace, applies
+that policy without mutating the live attempt, records the policy in the
+capture report, and then verifies the resulting patch or snapshot. Link and
+hard-link rejection remains unchanged. Hook serialization warnings are retained
+in the Agent SDK capture report and qualify the hook dimension as a gap rather
+than erasing an otherwise complete native session and hook stream.
+
+`captureClaudeAgentSdkRun` is the single-run production composition boundary.
+It reuses the existing lifecycle, caller-supplied workspace coordinator,
+passive Agent SDK sinks, optional verified-task result, assembler, and qualifier. It neither
+reads a run queue nor retries an attempt; an operational runner may call it once
+for each already-resolved queue entry.
+
+`qualifyRunBundle` performs the post-capture structural check without adding a
+new artifact dialect. Its report evaluates attempt identity, session evidence,
+pinned hook capability versus observed callbacks, telemetry receipt and
+optional timing, workspace outcome, assessment mode, any required verified-task result, terminal classification,
+and sharing classification independently. The overall result is `qualified`,
+`qualified-with-gaps`, or `unqualified`, with stable reason codes and the named
+evidence ID. Optional detailed-beta timing and a missing collector receipt are
+timing gaps; missing or malformed semantic/outcome evidence, an unusable patch,
+or contradictory capture-report facts are unqualified. The report contains no
+behavioral or semantic-quality judgment.
+
+An explicit `unsupported` capture-report capability remains qualified and is
+reported as `unsupported`, not rewritten as missing evidence. Qualification
+caps every retained artifact read at 64 MiB; larger evidence is rejected with
+`ARTIFACT_TOO_LARGE` before whole-file parsing. Parsed session records and raw
+telemetry payloads are not retained in the qualification report.
+
+Session qualification requires the descriptor, manifest, and every observed
+native session identity to agree. Hook JSONL must contain at least one pinned
+callback in `hook`, `hook_event_name`, or a source-specific `type`; unrelated
+nonempty JSON does not count as hook evidence. A telemetry artifact without a
+collector receipt is a `TELEMETRY_RECEIPT_MISSING` gap, including the supported
+usage-only path.
+
+Qualification reuses manifest schema checks, descriptor digest/path readback,
+mode-appropriate outcome binding, and export-manifest validation. When a
+workspace patch is present, callers supply the admitted starting fixture so the
+patch can be checked with `git apply --check`; omission leaves an explicit
+`WORKSPACE_PATCH_NOT_CHECKED` gap.
+
+## Portable export
+
+`createPortableRunBundleExport` reads a qualified run bundle without changing
+it and creates a separate partner or public derivative tree. Its policy fixes
+the artifact and string byte limits plus caller-supplied sensitive values. The
+exporter also removes credential-bearing environment values, local paths and
+usernames, hidden-reasoning fields, and disallowed raw API bodies. Run,
+attempt, bundle, session, and trace identities are replaced consistently so
+cross-artifact correlation survives without exposing native identifiers.
+
+The export allowlist covers JSONL session/hooks, JSON telemetry,
+text workspace patches, JSON verifier/capture reports, and text verifier
+diagnostics. Unknown classifications and unrecognized kind/media pairs stop
+the export. Restricted workspace snapshots may be retained up to 128 MiB for
+qualification, but portable exports explicitly exclude them as
+`unsupported-workspace-snapshot`; opaque archive bytes never pass through the
+text sanitizer. Existing source export manifests are likewise excluded and
+recorded rather than recursively exported.
+
+The derivative `export-manifest/v1` records each portable artifact's source
+digest, every applied transformation, each exclusion, the effective policy
+digest, and rewritten correlations. Creation reports success only after
+`readPortableRunBundleExport` rechecks schema, paths, digests, sizes,
+references, policy, JSON/JSONL structure, and a final secret scan. A failed
+creation removes its newly-created destination tree; an existing destination
+is never replaced.
+
+The remainder of this verifier section applies only to `verified` tasks.
+Verifier results cannot contradict their assertions: passed results have no
+failed assertion, while failed results retain at least one failed assertion.
+Assertion IDs are unique, and a retained verifier result names the containing
+bundle. Completed runs retain passed verifier results; task-failed runs retain
+at least one failed verifier result and may retain independent passed results.
+Both verified outcomes require retained verifier and workspace evidence; workspace
+evidence alone cannot establish task pass or task failure. A passed verifier
+result contains only passed assertions and, when retained, an exit code of zero.
+Every passed or failed verifier also names the retained workspace artifact and
+digest it evaluated.
+
+The executor receives both the retained workspace artifact reference and a
+separate live-workspace fingerprint; the executor options require the retained
+workspace reference to carry that same fingerprint. The v1 live-workspace fingerprint hashes
+the root and sorted descendant relative paths, entry kinds, permission mode
+bits, reproducible modification times, and file bytes; hard-linked files,
+symbolic links, and unsupported entry kinds are rejected. POSIX snapshots use
+the metadata-preserving system copy path with nanosecond modification times;
+the Windows fallback uses Node's reproducible millisecond precision. The
+fingerprint must
+match the live workspace before and after its private snapshot is created. The
+executor then evaluates that detached snapshot, while the artifact digest
+remains the digest of the retained workspace evidence. The complete executor
+result records the snapshot fingerprint alongside the workspace reference, and
+manifest workspace descriptors may carry it for later terminal binding checks.
+
+Verifier execution uses a small subprocess boundary. The executor resolves the
+digest-pinned restricted verifier from its task-bundle root, stages it in a
+private trusted subdirectory separate from the snapshot, and invokes the pinned
+Node runtime with the staged verifier path followed by the snapshot workspace
+path. Launcher options cannot replace the staged entry point, and the child
+environment contains only fixed coordinator variables; `PATH` points to a
+dedicated empty trusted-stage directory, while Node preload, POSIX dynamic-loader,
+shell-startup, and interpreter module-path injection are unavailable. Verifier
+tools must be invoked by absolute pinned paths. Normal completion is reported
+over a parent-owned extra stdio channel rather than a marker file or inherited
+environment variable, so ordinary workspace descendants cannot recreate it. The
+restricted implementation and any
+reference solution remain outside that workspace. `.mjs`/`.cjs` locators retain
+their module semantics; ambiguous `.js` or extensionless artifacts default to
+CommonJS unless the caller supplies `moduleFormat: "module"`, and explicit
+formats cannot contradict an unambiguous suffix. The verifier writes one JSON
+object to stdout:
+
+```json
+{
+  "assertions": [
+    { "id": "unit-tests", "status": "passed" },
+    { "id": "lint", "status": "failed" }
+  ]
+}
+```
+
+Each assertion object contains exactly `id` and `status`; undeclared fields,
+non-string statuses, duplicate IDs, and IDs longer than 256 characters are
+verifier errors rather than silently normalized away.
+
+The executor records the selected verifier's locator, digest, and module format, the assertion
+list, `durationMs`, observed `exitCode` when the process exits normally, and a
+`status` of `passed`, `failed`, or `error`. A run manifest may declare the
+task-bound verifier reference under `run.verifier`; manifest validation then
+requires each retained unsanitized verifier result to identify that same
+reference. A valid assertion failure is a task failure; timeout, crash, invalid
+UTF-8/JSON, duplicate or invalid assertion, and an exit/assertion contradiction
+are verifier errors. A failed assertion therefore requires a nonzero verifier
+exit; a zero exit paired with a failure is not a task result. `not-run` remains
+available for a caller that records a verifier which was never started, and its
+assertions must all be `not-run`. Stdout
+and stderr are drained without an unbounded buffer and persisted to private
+files while the process runs, so a partial attempt retains output even when
+execution ends abnormally. A timeout terminates the verifier process group (or
+process tree on Windows). Each retained stream is represented by an
+execution-specific diagnostic reference with a `stream` (`stdout` or `stderr`),
+bundle-relative `locator`, SHA-256 `digest`, retained `sizeBytes`, and a
+`truncated` flag. Sanitized verifier results may retain diagnostics only when
+each one carries a source diagnostic origin and points to a separately
+classified `diagnostic` evidence sidecar. The sidecar's path, digest, and size
+must match exactly, and it must be included in the export. The result remains
+valid even when diagnostics are truncated.
+The `durationMs` and `diagnostics` fields are optional for older v1 records;
+new executor results include both. An `error` result requires a nonempty
+explanation and may omit `workspace` when the verifier failed before a
+workspace was available; it must not invent a workspace binding. Coordinator
+failures such as timeout, launch, parse, or
+cleanup errors are recorded in the result's `error` field; the native stderr
+diagnostic remains byte-for-byte separate. `error` is not valid on passed or
+failed results. Sanitized verifier derivatives preserve `durationMs` and
+`error`; sensitive error text may use `errorRedacted: true` with the literal
+`[redacted]`, but cannot be replaced by an unmarked claim. The process-group boundary cannot
+contain a verifier that deliberately creates a new POSIX session; callers that
+run untrusted verifiers need an OS sandbox or equivalent isolation boundary.
+
+The result serializer validates `verifier-result/v1` before writing it. The
+diagnostic references are read back and digest-checked before the result is
+saved, so a result cannot point at missing or changed diagnostic bytes. Result
+paths use no-clobber persistence: an existing result, manifest, or other
+retained evidence file is never replaced by a later verifier write, and a
+crash between the no-clobber link and temporary-name cleanup is recovered on
+the next verified read. Manifest
+validation also cross-checks each retained verifier's `bundleId` and workspace
+artifact ID/digest against the containing bundle's retained evidence. The
+`manifest.json` path and its descendants are reserved for the containing
+manifest and cannot be used for verifier results or diagnostic directories.
+The CLI applies duplicate-key detection to standalone verifier JSON before
+parsing, just as manifest-nested verifier artifacts and subprocess output are
+checked before interpretation. Manifest validation requires a retained passed
+verifier for a completed verified run and a retained failed verifier for a
+task-failed run, and checks each verifier's status against that terminal
+outcome before the bundle is accepted. Observational completion instead
+requires retained workspace evidence and rejects verifier evidence.
+
+## Sharing boundary
+
+A partner export that lists restricted native artifacts is `blocked`. A `ready`
+or `exported` package resolves every artifact ID and requires every descriptor
+to have the export's exact sharing class. A public package therefore cannot
+bypass lookup or classification, and both partner and public packages need
+separately sanitized artifacts. Each such descriptor records `sanitizedFrom`
+with the retained source artifact ID and digest, and has a distinct bundle path;
+changing a native artifact's sharing class is not sanitization. The export pipeline performs the actual
+sanitization and readback; the v1 contract fixture makes the unsafe direct
+reference visibly blocked. A ready or exported manifest also names its
+containing bundle before its artifact list is approved. Ready and exported
+manifests contain at least one non-export evidence artifact; blocked and
+unrequested records may be empty but still name their containing bundle.
+
+The contract is intentionally only a declaration. Schema loading, safe path
+resolution, atomic persistence, and byte-level digest verification are shared
+artifact primitives delivered separately; no runner, adapter, exporter, or
+evaluation behavior is defined here.
+
+## Fixtures
+
+The four small fixtures under `test/fixtures/run-bundles/` establish the
+contract boundary:
+
+- `complete`: all five evidence authorities are referenced.
+- `task-failed`: a verifier-backed task failure is distinct from infrastructure
+  failure.
+- `interrupted`: retained semantic evidence plus an incomplete capture report;
+  no outcome evidence is invented.
+- `telemetry-incomplete`: semantic and outcome evidence remain available while
+  optional beta telemetry is explicitly absent.
+
+The checked-in Node contract test runs the schema, cross-descriptor uniqueness,
+sharing-path and export boundaries, capture-report correlation, capability
+evidence, artifact references/digests, retry identity, and representative
+rejected records. The later shared artifact validator reuses these fixtures; it
+owns filesystem hardening and persistence rather than a second contract.
+The build script clears compiled output first, and its regression test proves a
+stale compiled test cannot survive into test discovery.

package/docs/reference/run-lifecycle.md

@@ -0,0 +1,54 @@
+# Run lifecycle and process protocol
+
+`src/lifecycle.ts` owns one declared run cell and one attempt. A run is
+identified by task, model, and harness IDs; an attempt gets a fresh ID and
+number. `retryAttempt` links a later attempt with `retryOf`, so callers must
+choose a distinct record/evidence path. Attempt paths are reserved before any
+callback runs; an existing record path is never reopened by a new execution,
+and the runner never retries implicitly.
+
+The guarded attempt phases are:
+
+```text
+created -> setup -> running -> verifying -> cleaning -> terminal
+```
+
+Setup, harness execution, optional verifier execution, cleanup, and evidence flushing
+are injected callbacks. Setup and harness drivers can register independent
+shutdown handles for in-flight processes. `executeRunAttempt` passes an
+`AbortSignal`, enforces the coordinator and harness budgets, and records phase
+timestamps in an
+`ebo.attempt/v1` record. Each record declares `observational` or `verified`
+assessment. An observational attempt skips the verifying phase; normal harness
+termination plus retained workspace evidence is execution completion, not task
+success. Only a failed verifier on a verified task with retained workspace
+evidence is a task failure; a harness-declared task result without verifier
+evidence remains an infrastructure failure. A verifier execution error, setup
+error, harness error, or cleanup error after an otherwise successful run is
+also infrastructure evidence. A verified completed attempt needs both a passed
+verifier and a retained workspace artifact; an observational completed attempt
+needs the workspace artifact and carries no verifier evidence. Missing capture flush support is
+explicit as `capture-incomplete` and does not become a task failure.
+
+`src/process-protocol.ts` is a narrow process boundary, not a JSON-RPC
+implementation. `ProtocolProcess` parses newline-delimited JSON only to reject
+malformed stdout, keeps stdout machine-only, and drains bounded stderr into a
+diagnostic result (and optional `stderrPath`). `ProtocolEvidenceRecorder`
+retains raw frames plus caller-supplied request, response, notification,
+completion, and capability observations. Drivers provide method names,
+correlation IDs, native identities, and completion evidence; the runner does
+not infer prompt completion or map records into EBO event families.
+
+JSONL records are flushed and fsynced as they arrive. Valid frames retain their
+original line text alongside parsed data, so duplicate keys or large numeric
+IDs cannot be silently rewritten by a JavaScript round trip. The stdout line
+limit is enforced while bytes are consumed. When a caller supplies a JSONL
+writer, the process derives a conservative effective stdout limit from that
+writer's per-record envelope capacity so retaining both raw and parsed frame
+evidence cannot turn a valid frame into an append failure. In-memory
+observations use a bounded tail; the JSONL file remains the complete source
+record. Interruption and malformed output therefore leave a readable partial
+evidence file and a process result with launch identity, exit/signal state, and
+termination reason.
+`shutdown()` and `interrupt()` are explicit operations; no process retry is
+performed.

package/examples/cursor-sdk/README.md

@@ -0,0 +1,11 @@
+# Cursor SDK input example
+
+These five records are the minimal Cursor-specific inputs referenced by an EBO
+experiment. Copy them into the caller-owned bundle, replace the model
+placeholder with an exact ID returned by `Cursor.models.list()`, compute the
+normal EBO artifact digests, and reference them from the experiment's model,
+harness, native-limits, native-tool-policy, and capture-profile fields.
+
+Use the standard `task-packet admit`, `task-packet freeze`, `matrix compile`,
+`queue validate`, and `cursor run` commands. No Cursor-specific preparation
+script or cloud agent is required.

package/examples/cursor-sdk/capture-profile.json

@@ -0,0 +1 @@
+{"schemaVersion":"ebo.cursor-sdk-config/v1","kind":"capture-profile","nativeOtlp":"unsupported","workspaceOutcome":{"excludeDirectoryNames":["node_modules"]}}

package/examples/cursor-sdk/harness.json

@@ -0,0 +1 @@
+{"schemaVersion":"ebo.cursor-sdk-config/v1","kind":"harness","adapter":"cursor-sdk","sdkVersion":"1.0.31"}

package/examples/cursor-sdk/model.json

@@ -0,0 +1 @@
+{"schemaVersion":"ebo.cursor-sdk-config/v1","kind":"model","provider":"cursor","model":{"id":"REPLACE_WITH_EXACT_CATALOG_MODEL"}}

package/examples/cursor-sdk/native-limits.json

@@ -0,0 +1 @@
+{"schemaVersion":"ebo.cursor-sdk-config/v1","kind":"native-limits","shutdownGraceMs":2000,"maxNativeRecordBytes":16777216}

package/examples/cursor-sdk/native-tool-policy.json

@@ -0,0 +1 @@
+{"schemaVersion":"ebo.cursor-sdk-config/v1","kind":"native-tool-policy","tools":["read","edit","grep","glob","ls"],"disallowedTools":["shell","task","mcp","webSearch","webFetch"],"sandbox":{"enabled":false},"settingSources":[],"autoReview":false,"enableAgentRetries":false}