@juli-os/artifacts — L2 Artifacts Layer (peel validation slice)

The L2 layer of the juli-os ladder: hash-registered deliverables with provenance. Content stays schema-free; the registration ledger is the only structure. Zero npm dependencies — the disk backend works out of the box, and S3-compatible presign is hand-rolled (no SDK).

What's inside

Capability	API	What it gives you
Backends	createDiskBackend(root) / createS3Backend(opts) / createDualBackend(primary, remote)	Pluggable storage with traversal protection on the disk backend
Registration ledger	createArtifactLedger(db, backend) → putAndRegister / register / get / list / tombstone / updateMeta	Every deliverable lands with sha256, role, name, mime, bytes, key — immutable once registered
Tamper evidence	register → later recompute	Content that no longer matches its registered hash is detectable immediately
Envelope parsing	parseEnvelope / isDeliverableRef	Typed deliverable references inside agent outputs
Case inbox sweep	sweepCaseInbox	Collect and register deliverables from a working directory

Peel boundary

Files are copied verbatim from the juli monorepo (import paths unchanged):

File	Origin
src/platform/artifacts/{ledger,store}.ts	src/platform/artifacts/
src/platform/shared/{json,result,clock}.ts	src/platform/shared/

Dependency rule: artifacts → shared, strictly downward. Consumers may only import the facade src/index.ts.

Quick start — no install step

Requires Node ≥ 22.18 (built-in type stripping + node:sqlite).

node bin/juli-artifacts.ts demo /tmp/demo-artifacts    # seed 3 artifacts
node bin/juli-artifacts.ts ls /tmp/demo-artifacts       # list registrations
node bin/juli-artifacts.ts verify /tmp/demo-artifacts   # recompute hashes vs registrations

Or from code:

import { createDiskBackend, createArtifactLedger } from '@juli-os/artifacts';
import { DatabaseSync } from 'node:sqlite';

const backend = createDiskBackend('./store');
const ledger = createArtifactLedger(new DatabaseSync('./artifacts.db'), backend);
const row = await ledger.putAndRegister({
  workflowId: 'wf_1', role: 'agent_output', name: 'summary.md',
  bytes: Buffer.from('# Hello\n'), mime: 'text/markdown',
});
// row.sha256 is now the receipt for those exact bytes

Run the test suite (zero npm install):

node --test "test/*.test.ts"

This is a validation slice

Second empirical test of the "layers you can peel off" hypothesis (adopt at your altitude). Verified green on macOS node 22 and a bare Linux box on node 24 — including tamper-detection: mutate the stored bytes and verify fails loudly.

License

Apache-2.0