Skip to content
Crosswalker
🚧 Early alpha — building the foundation. See the roadmap →

v0.1.8 — Execution records, audit, and package manifests

Updated

Make every run inspectable before adding stronger attestation around it. The primary artifact is an Execution Record: one schema-valid receipt answering what actually happened for one bound run. Per-note provenance and durable log events link to that record. Existing git, Ed25519 signing, and FRE 902(13) mechanisms consume the record rather than reconstructing run facts independently. A Package Manifest is separate: it inventories, hashes, and optionally attests the artifacts distributed in one release. See the artifact roles and authority and artifact-role synthesis.

Status

Section titled “Status”

📋 Planning

Status last verified: 2026-09-05 — scoped to planning state and artifact boundaries at commit 30aee63b: the milestone hub still marks v0.1.8 as Planning, spec/README.md states that neither the Execution Record nor Package Manifest contract is defined yet, and no src/audit/ implementation directory exists. The scope below is a proposal; no run-history, signing, package-inspection, or other UI/runtime behavior is claimed or verified.

Dependencies

Section titled “Dependencies”

Scope

Section titled “Scope”

In:

  • Execution Record contract — one terminal receipt per run, including status, timing, recipe reference/hash, exact source-byte hash, parser selectors, destination/parameters, output inventory/hashes, validation outcomes, warnings/deviations, and trace identity
  • Execution-linked provenance — generated Tier 1 notes and durable NDJSON events carry the same execution ID without pretending either is the complete aggregate receipt
  • Run-history UI — browse, filter, inspect, and export prior Execution Records; both UI and programmatic import paths use the same recorder
  • Git audit consumer — successful runs can produce one deterministic commit whose message summarizes the Execution Record
  • Ed25519 signing and FRE 902(13) certification consumers — attest a Package Manifest and its referenced execution evidence instead of signing an underspecified folder
  • Package Manifest contract — separately inventory a distributed release’s Knowledge Sets/MappingSets, reusable configurations, relevant Execution Records, dependencies, licenses/attribution, versions, paths, and content hashes
  • Package-inspection UI — inspect inventory, verify hashes/signatures, and export the manifest before distribution or installation
  • Logging-infrastructure production-hardening sub-phase — retain one wide-event NDJSON substrate, but separate rotating debug output from non-stripped execution/audit events

Out:

  • T2 / T3 audit profiles (OpenTimestamps, RFC 3161, Sigstore Rekor v2 + in-toto, eIDAS QTSA + W3C VC) — opt-in compliance-export mode for v1.0+
  • Community package discovery/install/update lifecycle — later Community phase
  • PQC dual-sign migration — 2027+ work per NIST IR 8547 timeline

Concrete tasks

Section titled “Concrete tasks”

Execution Record first

Section titled “Execution Record first”
  • Define and validate the versioned Execution Record contract; keep it distinct from per-note _crosswalker provenance, debug logs, and Package Manifests
  • Write exactly one terminal record for success, failure, or cancellation through both UI and programmatic run paths
  • Correlate output notes, validation results, warnings, and durable log events by execution ID
  • Add run-history browse/filter/inspect/export UI
  • Test deterministic record serialization, terminal-status coverage, source/recipe hash capture, and output inventory integrity

Audit and attestation consumers

Section titled “Audit and attestation consumers”
  • Git integration — consume a successful Execution Record and produce one deterministic commit message with recipe/run identity, concept count, and summary diff
  • Ed25519 sign/verify helper — use a configured key reference; signatures attest the Package Manifest bytes
  • FRE 902(13) PDF template — derive the certification fields from the verified Package Manifest plus referenced Execution Records
  • Settings UI — explicit commit/sign controls and key-source selector; signing remains opt-in
  • Tests — commit message determinism, sign/verify round-trip, tamper detection, and FRE 902(13) rendering

Package Manifest separately

Section titled “Package Manifest separately”
  • Define the versioned Package Manifest contract and canonical vault path independently from the Execution Record contract
  • Inventory every distributed artifact with role, identity/version, path, byte hash, dependencies, provenance/license, and optional execution-record reference
  • Verify inventory completeness and hashes before signing, exporting, or installing a package
  • Add package inspect/verify/export UI and equivalent programmatic APIs

Logging-infrastructure production-hardening sub-phase

Section titled “Logging-infrastructure production-hardening sub-phase”

Rationale: the debug logger and execution/audit event streams can share plumbing without becoming the same artifact. Phase 3.5a/b/c shipped the NDJSON wide-event logger (src/utils/debug.ts, trace correlation via withTrace, categories, levels). v0.1.8 closes the production gaps while preserving the Execution Record as the aggregate run receipt:

  • Bundle stripping — add esbuild define flag (__DEBUG__); strip trace/info debug emit sites from production while retaining execution/audit and error/warn paths
  • Log rotation — cap rotating debug output at MAX_LOG_LINES; durable execution/audit records are governed separately
  • Settings surface — expose logLevel: 'error' | 'warn' | 'info' | 'trace'; default info
  • “Copy redacted log slice for bug report” command — scrub absolute paths, usernames, email-shaped strings, and secrets before copying
  • Execution/audit event stream — emit non-stripped NDJSON events keyed by execution ID for record-written, commit-written, package-verified, signed, and manifest-published outcomes

Success criteria

Section titled “Success criteria”
  • Every terminal UI or programmatic run produces exactly one schema-valid Execution Record, including failed and cancelled runs
  • Execution Record recipe/source hashes and output inventory verify against the bound reusable configuration, exact source bytes, and generated files
  • Per-note provenance and durable log events resolve to the same execution ID without duplicating the aggregate contract
  • Run-history UI can inspect/export records and clearly surface failures, warnings, validation outcomes, and source drift
  • Successful-run git commits are deterministic consumers of Execution Records; disabling commit/sign controls causes no hidden audit side effects
  • Package Manifest inventory is complete, byte hashes verify, tampering fails verification, and Ed25519 signatures attest the manifest bytes
  • Package-inspection UI and programmatic verification report the same result
  • FRE 902(13) PDF derives from verified package/run evidence and contains the required certification fields
  • No Tier 2/Tier 3 audit dependencies in v0.1.8
  • Logging sub-phase: production debug code shrinks measurably; rotation bounds debug logs; log-level controls work; redacted slices contain no absolute paths, usernames, email addresses, or secrets

Files to touch

Section titled “Files to touch”
  • spec/ — versioned Execution Record and Package Manifest contracts
  • src/audit/ — record writer, git consumer, signing, manifest verification, FRE 902(13)
  • src/generation/ and import orchestration — terminal run hooks + execution correlation
  • src/settings/settings-tab.ts — commit/sign/log controls
  • run-history and package-inspection UI modules
  • unit + real-Obsidian E2E coverage for UI and programmatic paths

Open questions

Section titled “Open questions”
  • Canonical vault paths and retention policy for Execution Records and Package Manifests
  • Do we shell out to system git, or use a JS library? simple-git exists but adds a dependency
  • Key management UX — file reference vs. OS credential store; choose a portable v0.1 floor without storing private key material in manifests or logs
  • FRE 902(13) PDF — fully programmatic via pdf-lib, or a templated approach?
Section titled “Related”

Concept pages:

Agent context:

  • Vision — file-based canonical state enables git-native audit
  • Tradeoffs — T1 (git) vs. T2 (OpenTimestamps/RFC 3161) vs. T3 (Sigstore Rekor + in-toto, eIDAS QTSA)
  • Decisions

Design decisions (synthesis logs):

Research deliverables:

External references:

Other milestones: