The Data-Shape Ledger

Extracted against the code of the v0.5.5 release line (2026-08-19). This follows the DATA, not the control: where the invocation map walks the verbs, this walks the values. Spec coverage comes from the live registry, not from memory — all 118 src/ namespaces loaded into one JVM yield 675 keyword specs across 58 spec namespaces and 101 fdefs, a census this ledger reconciles station by station. The worked trace uses real captured EDN from a live scenario run.

The chain in one paragraph

Two files enter (the project’s shiftlefter.edn, the machine’s ~/.shiftlefter/config.edn); project-context/resolve turns cwd + flags into location facts; runner.config/load-config merges and validates the project config. From there the chain forks and rejoins: the run leg loads glossary + intents, parses features into pickles, binds them into run plans (where the SVO map is stamped), threads a ctx stash through execution, and folds step → scenario → suite → run results; the query leg (orient/glossary/explain) rides build-projection over the same loaders and emits version-stamped EDN. Everything the run wants to say crosses ONE seam — the reporter envelope discipline — and leaves as the locked --edn summary (payload by attachment ref), the bus event envelope, or a rendered report in results/<stamp>/. The stability story is deliberately tiered: inputs are spec-validated at the boundary, outputs are contracted by docs + additive discipline (§ Stability tiers).

The ledger

One station per boundary shape. Producer pins are definition lines at the 2026-08-19 extraction (§ 1’s config pins re-verified 2026-08-23); “spec” is the registered s/def keyword (— means none registered: the contract is docstring/doc, see § Stability tiers).

1. Project config — shiftlefter.edn

• Top-level key set: #{:parser :runner :glossaries :interfaces :costumes :svo :timing} (known-top-level-keys config.clj:520-528). :errors is synthetic, added only by normalize.
• Mode invariant (config.clj:339-343): the loaded map contains :svo iff the user’s file did. :svo presence IS Shifted mode — stepengine/compile.clj:62 and project_projection.clj:471 both key on it.
• The one computed default (config.clj:307): :unknown-object flips to :warn iff [:glossaries :intents] is configured, else :off — apply-conditional-object-default is the single place this is decided (visible live in the trace below).
• Conventional glossary probing (config.clj:278) runs only when the user config has no :glossaries key at all — whole-map semantics.
• Nested maps (:interfaces entries, adapter :config) are open by design; :webdriver/:webdriver-url deliberately excluded.

2. Machine config — ~/.shiftlefter/config.edn

• resolve-chromedriver-path user.clj:130 is the declared single source of truth for driver discovery (:path-driver opt → :chromedriver-path → PATH), shared by fresh-spawn and costume paths so they cannot drift.

3. Project context

• Key set: :invocation-root :workspace-root :project-root :config-root :config-path :config-source :layout :portable? :diagnostics (project_context.clj:167-199). :config-source ∈ #{:explicit :discovered :defaults}; :layout ∈ #{:sl-directory :root :defaults}.
• Cross-process lockstep: instance-root (project_context.clj:201) MUST match bin/sl’s find_instance_root exactly — the shell wrapper and daemon agree on .shiftlefter/daemon.edn by parallel implementation, not shared code.
• Discovery is closed to <candidate>/sl/shiftlefter.edn (the sl/ directory layout); root-level configs are no longer discovered; -c FILE is the escape hatch.

4. Projection

• Full key set at project_projection.clj:466-488: :projection/id (fresh UUID) · :projection/version · :built-at · :project-context · :source (:working-tree, closed set :25) · :status · :mode · :config · :substrate · :svo-effective · :subjects :instances :interfaces :verbs :intents :stepdefs :macros · :diagnostics · :validation-commands · :inputs · :fingerprint.
• The fingerprint key set is a contract (project_projection.clj:411-425): sha256 over exactly [:projection/version :project-context :source :inputs :config :subjects :instances :interfaces :verbs :intents :stepdefs :macros :diagnostics]. :substrate (config-path + config-source + git sha/dirty) is DELIBERATELY outside it — “the fingerprint is content identity; substrate is the citation”. Adding a key to that select-keys breaks fingerprint stability.
• :inputs entries are {:kind :path :exists? :digest} per contributing file (kinds: :config :glossary/subjects :glossary/verbs :glossary/intents :stepdef :macro).
• Macro entries carry their own nested :representation-version 1 (project_projection.clj:264).
• Same-path doctrine: the projection resolves through the run’s own loaders (never a parallel path), so a listing can never disagree with the run it predicts — see invocation-map § query family.
• Degraded branches (:485-499, :534-546) emit strictly smaller key sets; consumers must tolerate absence.

5. Resolution outputs — sl glossary / sl explain --edn

• Structural wording discipline (addendum 2): full-corpus entries carry :unused?, scoped selections carry :referenced-in-selection? — distinct keys so a consumer cannot read a scoped verdict as deletion license (marker-keys resolution.clj:203).
• The projection :fingerprint rides glossary-edn (:362) but not explain-edn.
• The :usage block is fed by projection.usage-index/bind-corpus (usage_index.clj:57), which re-enters discover→parse→compile with the run’s own binder; its flat tuples (:152-172) are the node/edge vocabulary later graph tooling consumes — deliberate groundwork (:20-22).

6. Glossary

• Runtime key set is a superset of the spec: :subjects :verbs (spec’d) plus loader-added :provenance :sources :instance-index. :verbs mount keys are the types the FILES declare (:type required and authoritative; config :glossaries :verbs is a plain path list), and :sources :verbs maps each declared type to the file that mounted it.
• Merge is wholesale-per-key (glossary.clj:48-60): a project entry replaces the builtin entry entirely, documented lossy. The :override-defaults flag was REMOVED — glossaries always extend; a file carrying the key draws a load-time warning.
• Frame sub-shape carries the slot vocabulary the binder stamps from: ::object-kind #{:intent :location :text :key}, ::arg-kind #{:value :matcher}.

7. Intents

• Global cache boundary: intent.state/get-intents state.clj:41 (memoized; throws on load error) — REPL convenience; the runner resolves config-root explicitly.

8. Pickles

• Req keys: :pickle/id :pickle/name :pickle/source-file :pickle/location :pickle/tags :pickle/steps; step req keys: :step/id :step/text :step/keyword :step/location :step/origin :step/arguments.
• IDs are random per run (randomUUID at pickle time, pickler.clj:303/:395) — contrast stepdef/id = deterministic "sd-" + sha256(pattern-src)[0:16] (registry.clj:134), the only stable ID in the chain.
• The pickle is not frozen at pickler exit. Additive step keys are assoc’d downstream, outside ::pickle-step: :step/declared-interface (annotations.clj:201), :step/synthetic? + :step/macro (macros.clj:240-261). :step/text keeps the [iface] annotation intact; stripping happens at match time (bind.clj:306).

9. Bound plans — the SVO map

• Two shapes share the nickname “SVO” — the authored placeholder form (:object :$1) on stepdef metadata, and the runtime substituted form on the binding. The ledger treats them as distinct rows; conflating them is the sharpest naming hazard in the chain.
• Bind-time rewrites of the runtime SVO: :interface is overwritten with the resolved execution INSTANCE (bind.clj:376-380) — after binding it is an instance name, not the type; validate-svo re-derives the type via config (validate.clj:442-444). :wears is stamped at bind time (bind.clj:563-579) so runtime provisioning never needs the glossary threaded.
• Validation issues: ::svo-issue validate.clj:65 with a closed ::type set :48-57 (includes the :bindings/* family).

10. Ctx stash

• Reserved families: :cap/<iface>[.subject] → {:impl :mode :cleanup-handle} (ctx.clj:116; NOT EDN-safe — live drivers); :run/interfaces (:166) and :run/timing (:186), stashed once per scenario; :sl/bindings → flat {lowerCamel-kw → edn value} (bindings.clj:32), the scenario data plane: forward-only, last-write-wins, dead at scenario end, provenance rides run evidence (:bindings/produced) never the map.
• Mutation asymmetry (exec/hooks.clj:29-33): a step’s map return REPLACES ctx wholesale (step_loop.clj:93-95); Before-hook returns MERGE.
• ctx never crosses the reporter seam — scenario-envelope drops :scenario-ctx by allowlist (reporter.clj:263).
• Step-visible metadata travels on the ctx map’s METADATA, not in it: :step/arguments :step/text :step/keyword :step/interface stamped at step_loop.clj:72-79, read via the shiftlefter.step accessors (step.clj:59-92).

11. Result records

• The exit-code table is its own locked contract (verdict.clj:37): locked at 0.5.1, reopened STRENGTHEN-ONLY for the 0.5.5 window, re-locks at the contracts release — see invocation-map § verdict contract.

12. Reporter envelopes — the seam

• Four load-bearing invariants (reporter.clj:15-71 — marked do-not-relax; loosening any of them is an architecture decision, not a patch): coordinator thread only; plan order on the report plane (actual order + :seq on the bus); pure EDN-native data — scrub (:222) kills live drivers/fns/atoms and flattens defrecords, pr-edn-str (:200) pins printer bindings; exit-code independence with loud failure.

13. The --edn run summary + attachment refs — the locked contract

• Top-level keys: :run/id :run/seed :run/exit-code :run/status :counts :dropped-events :planning :failures :attachments :diagnostics :error; dry-run variant adds :dry-run :group :filtered-out :hooks (core.clj:962).
• There is no version key. Versioning is additive-only key growth plus the consumer rules (REPORTS.md:41-54): stdout is a form STREAM; skip shapes you don’t recognize; gate on exit code, route on the record. This is the house pattern for machine OUTPUT surfaces — see § Stability tiers.
• The contract stays EDN-native (tagged UUIDs, bare symbols survive typed); lowering for JSON consumers is a foreign-worker transcoder’s job, not an envelope constraint (reporter.clj:54-60).
• The summary is NOT a file — nothing like summary.edn lands in the run directory (REPORTS.md:18-21). Redirect stdout to capture it.

14. Bus event envelope

• Event types at this stamp: :test-run/started :test-run/finished :scenario/finished :step/svo (payload {:subject :verb :object :interface :interface-type :step-text :location}, step_loop.clj:147-153).

15. Reports + the run-results directory

• Reporter protocol: Reporter reporter.clj:367 (on-run-start/on-scenario-complete/on-diagnostics/on-run-end); emit-lifecycle! (runner/core.clj:554) is the single call site per moment — reporters synchronously in plan order, then the same moment to the bus. Reporters are never bus subscribers (ARCHITECTURE.md § Reporting).

Stability tiers

The chain’s contracts are deliberately tiered — the strength of the guarantee tracks who consumes the shape:

The pattern behind the tiers: inputs are spec-validated at the boundary (the Clojure-module convention — no unvalidated external data reaches core functions), while machine OUTPUT surfaces are contracted by docs + additive discipline (the --edn summary is the established precedent).

The worked trace — one scenario, four machine surfaces

All captures REAL, from examples/04-sms-2fa at the 2026-08-19 extraction, one scenario (“Alice resets her password using a code sent to her phone”, 8 steps, two interfaces, zero custom steps), run live with ChromeDriver + the example’s fixture server. Substrate stamps the claim — the :git-sha names the development tree the trace ran on, quoted as captured: {:config-source :discovered, :git-sha "39468a25", :git-dirty? false}.

Station 1-2 (config in). The project config declares two interfaces and three :svo levels — and deliberately omits :unknown-object:

{:interfaces {:web {:type :web :adapter :etaoin :config {}}
              :sms {:type :sms :adapter :sms-mock}}
 :svo        {:unknown-subject :error
              :unknown-verb    :warn
              :unknown-interface :error}}

Station 3-4 (context → projection). sl orient --edn emits the projection verbatim. :mode :shifted (the :svo key is present). The conditional default is visible: intents are configured, so the effective levels gained :unknown-object :warn:

:svo-effective {:unknown-subject :error, :unknown-verb :warn,
                :unknown-interface :error, :unknown-object :warn}
:projection/id "proj-87a5c62e-341b-4045-8447-26809c0500b8"
:projection/version 1
:fingerprint "cdbc7c77844aa95b17c645a4be4e81761886db918764845b6574707b9a3effdc"

Each contributing file rides :inputs with a digest — content identity, not just a path:

{:kind :config,
 :path ".../examples/04-sms-2fa/sl/shiftlefter.edn",
 :exists? true,
 :digest "d9bbd9a37a13223e5c08719eeec5c51e8db08882d7cfd4af2c2d6bf26d4b546d"}

The adapter registry surfaces as :adapter-metadata per interface, with PROVENANCE: an interface on an undeclared builtin adapter shows the default entry’s full fields (:provenance :builtin-default, :impl-key, :provides, :capture-kinds, :has-on-provision?). An adapter that setup.clj declares shows :provenance :declared with the declaration’s data. Example 04’s :sms-mock pins its runtime fields as pure data (:impl-key nil, :on-provision? true), so its entry carries them outright and the registry contract verifies the live entry against the pin at station 10:

{:known? true, :provenance :declared,
 :provides [:shiftlefter.sms.protocol/ISMS
            :shiftlefter.sms.protocol/ISMSInbound],
 :capture-kinds [], :impl-key nil, :has-on-provision? true}

A declaration that does NOT pin them instead gets :runtime-unknown [:impl-key :has-on-provision?]: those are facts of the registry :start returns at station 10, not of the plan-time declaration, so the projection names them unknown rather than guessing from the default entry — a :start may legitimately return an override without the default’s hook or with a different impl shape, and a guessed :has-on-provision? true would then be a lie.

Station 5 (resolution). sl glossary --edn (:resolution/version 1) shows the corpus-riding usage markers — full-corpus scope, so the key is :unused?, never :referenced-in-selection?:

{:type :user, :description "Standard application user",
 :instances [:alice], :singleton? false,
 :provenance :user-file, :unused? false, :use-count 8}

Stations 6-9 (glossary/intents → pickles → bound plan). sl run --dry-run --edn stops at compile — a plan verdict, not a run verdict (:run/status :dry-run, exit 0 = the selection binds). The setup.clj group names itself, and the SVO validation tier already speaks:

{:run/id "83064bcd-…", :run/seed 1187363736201345408,
 :run/exit-code 0, :run/status :dry-run,
 :counts {:scenarios 1, :steps 8}, :group "sms-2fa",
 :diagnostics {:svo-issues [… 2 issues …], :counts {:svo-issue-count 2}}}

Stations 10–13 (execution → envelope). The live run. In flight, the (?<code>\d{6}) named group on the SMS receive step binds code into :sl/bindings; two steps later {code} resolves it back into the fill — the scenario data plane doing its one job. The captured summary (stdout; stderr carried only the run seed: line):

{:run/id "3de3400c-b959-430c-93cf-9c5663a3f930",
 :run/exit-code 0, :run/status :passed,
 :run/seed 5788014003369720924,
 :counts {:passed 1, :failed 0, :pending 0, :skipped 0,
          :scenarios 1, :steps 8},
 :diagnostics
 {:svo-issues
  [{:type :svo/unknown-object, :object "Enter Verification Code",
    :message "Invalid intent reference: …",
    :location {:step-text ":user/alice should see 'Enter Verification Code'",
               :step-id #uuid "5b43275a-…", :uri ".../password_reset_sms.feature",
               :line 11, :column 5},
    :severity :warn}
   {:type :svo/unknown-object, :object "Code verified for alice", …}],
  :counts {:svo-issue-count 2}}}

Every ledger claim is visible in miniature: the locked summary’s key vocabulary; counts with :error absent (zero); #uuid tagged literals surviving typed (EDN-native stance); the ::svo-issue shape with its closed :type and full :location; and the two :warn diagnostics are the default from station 1 firing on the two free-text assertions — config decision in, diagnostic severity out, one chain.

Station 15 (disk). The run created sl/results/20260819T144724Z/sms-2fa/ — stamp from the group’s :started-at, slug subdir because setup.clj declares an explicit group. No summary.edn — the record went to stdout.

Siblings

• invocation map: the verbs these shapes travel under; its § spine is this ledger’s control-flow dual.
• module map (require-graph truth).
• REPL custody & lifetimes: what outlives the invocation; this ledger’s ctx/capability rows at rest.
• the control loop: these shapes in motion — the firing order that produces them, and the ctx contract per stage (station 10’s time-axis half).

How this map stays true

This page is a mechanical projection of a live-maintained internal map: re-verified against the code by probe runs at each re-stamp, regenerated — never hand-edited — by the derivation pipeline, and drift-guarded by the test suite (a hand edit here fails a test). File:line pins are re-verified at each re-stamp.