Skip to content

docs: organize Stage 06 persistence postures#258

Merged
roackb2 merged 2 commits into
mainfrom
codex/local-json-storage-example
Jul 20, 2026
Merged

docs: organize Stage 06 persistence postures#258
roackb2 merged 2 commits into
mainfrom
codex/local-json-storage-example

Conversation

@roackb2

@roackb2 roackb2 commented Jul 19, 2026

Copy link
Copy Markdown
Owner

Why

A new adopter can use Heddle's default files, but the onboarding path did not
prove the operational promise: one persistent host, paired session/archive
recovery, and whole-state-root backup and restore.

The examples also exposed a ladder-shape problem. Local JSON and PostgreSQL are
alternative persistence postures within one customization stage, but two
top-level 06-* directories made them look like duplicate sixth steps.

What

  • add a runnable local JSON recovery proof with no model credential
  • recover the complete session, archive manifest, and rolling summary through
    a fresh engine
  • snapshot and restore an isolated complete state root
  • group Stage 06 under examples/sdk/06-persistence/
    • local-json/ for one durable host using Heddle defaults
    • postgres-drizzle/ for a host-owned shared PostgreSQL adapter
  • add a Stage 06 chooser that makes the alternatives and host responsibilities
    explicit
  • update scripts, Drizzle configuration, source imports, guides, and package
    paths for the new layout
  • preserve the existing package boundary: the local verifier ships, while the
    PostgreSQL reference remains excluded host-owned example code

This does not add a storage abstraction, official database adapter, or durable
in-flight execution promise.

Verification

  • HEDDLE_EXAMPLE_STATE_ROOT=/private/tmp/heddle-pr258-local-json.LprgJN yarn example:local-json-storage:verify
  • isolated PostgreSQL 17: migration plus yarn example:postgres-storage:verify
  • yarn test: 122 unit files / 719 tests and 34 integration files / 310 tests
  • yarn typecheck
  • yarn lint
  • yarn build
  • npm dry-run manifest: new local JSON path included; PostgreSQL reference and
    both old paths excluded
  • relative-link validation for all eight changed Markdown entry points
  • git diff --check

@roackb2 roackb2 changed the title docs: add local JSON durability example docs: organize Stage 06 persistence postures Jul 19, 2026
@roackb2
roackb2 marked this pull request as ready for review July 20, 2026 06:10
@roackb2
roackb2 merged commit 3e489a7 into main Jul 20, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant