Skip to content

Ledger: write and read run files in softfac's JSONL format #9

Closed

Description

@tomkaczocha

Outcome

The fork records every run in the same files and format as softfac, so softfac runs list and softfac retro read the fork's runs with no changes.

Acceptance criteria

  • apps/server/src/factory/ledger/ writes run files <data>/runs/<owner>__<repo>__<issue>__<attempt>.jsonl and the machine log <data>/events.jsonl, as softfac's docs/reference/ledger.md describes. Lines are {"ts","ms","event","data","cause"} (cause left out in the machine log), names are lowercased, files are append-only, each line is one write followed by fsync, and a new run file is created only if it does not exist.
  • <data> is the factory data dir from paths.ts when that exists, else a parameter.
  • The reader returns a file's events in order and treats a torn last line the way softfac's reader does.
  • Event names and data fields are the ones in ledger.md. The writer refuses an event name the doc does not list.
  • The format and crash-rule cases from the tests in softfac's src/ledger.rs are ported and pass.

Depends on

Notes

After merge a person checks compatibility by hand: write a few runs with a test, then softfac runs list --data-dir <that dir> and softfac retro --data-dir <that dir> read them.

Reference

  • softfac, the Rust factory this ports, pinned at rawphp/softfac@bf273a1. Read it from a separate clone: git clone --filter=blob:none https://github.com/rawphp/softfac /tmp/softfac-ref && git -C /tmp/softfac-ref checkout bf273a1d93651992b4fc95b4dd6c111f8f3322cf. Its docs/lifecycle.md, docs/reference/ledger.md and docs/issues.md describe the behaviour; its tests pin it.
  • Design: factory/docs/design.md in this repo.
  • Upstream's AGENTS.md applies. Run only the tests and typechecks for the paths you touch (vp test run <path>, vp run --filter t3 typecheck), never the repo-wide checks.
  • Edit no upstream file that is not listed in factory/SEAMS. A new seam needs a line in factory/SEAMS and a reason in the PR body.
  • Port behaviour, not code: port the named test cases first (TypeScript, vitest / @effect/vitest), then make them pass. Exact comment and ledger wording is ported as is.

Activity

  1. added and removed
    factory:proposedA bot filed it; ignored until a person sets ready
    on Oct 15, 2026
  2. added and removed on Oct 15, 2026
  3. self-assigned this
    on Oct 15, 2026
  4. added and removed on Oct 15, 2026
  5. rawphp commented on Oct 15, 2026

    @rawphp

    Factory status: pr-open

  6. added
    factory:pr-openPR is open and passed the gate
    and removed on Oct 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

factory:pr-openPR is open and passed the gate

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions