halfcycle 0.3.32 → 0.3.33

package/dist/build-record/index.d.ts

@@ -1,42 +1,20 @@
 /**
- * @halfcycle/bundle — Build-Record assembler public API.
+ * @halfcycle/bundle — the Build Record's client half.
  *
- * At phase close, one bundle step (`halfcycle build-record <phase>`, D1) reads a
- * phase's LOCAL artefacts and writes `docs/build-records/phase-<N>.{md,json}`
- * with `format: "halfcycle-build-record/v1"`. No record content is hand-authored;
- * the markdown data slots project from the JSON.
+ * Closing a phase freezes its record on the service; the CLI fetches that frozen
+ * record and writes it into the client's repository as
+ * `docs/build-records/<segment>.{json,md}`. Nothing here assembles a record from
+ * local files: the local assembler, its `.workbench` close record and every local
+ * source it read left the shipped CLI in Connect Phase 4
+ * (`close-produces-the-record`), which is what removed the orchestration-state
+ * requirement no Connect client could meet (`#1400`).
  *
- * Two safety-by-construction seams:
- *   INV-007 — guard rows enter only as `FiredGuard`-subset `SeedGuard`s
- *             (`projectSeedGuards`); a `GuardRecord`/matcher/channel/version can
- *             never appear (the wire types physically lack those fields).
- *   INV-001 — every source is a LOCAL file; no hosted store / control-plane
- *             import or call. `packages/bundle` ⊆ {core, events}.
+ * INV-001 — this module and everything it re-exports import only
+ * `@halfcycle/events` and Node builtins. The record's schema, the response schema
+ * and the phase grammar each have one home there; nothing here restates them.
  */
-export { BUILD_RECORD_FORMAT, projectSeedGuard, type SeedGuard, type Delivered, type DoneWhenResult, type Acceptance, type GatesEarnedKeep, type Instruments, type Tasks, type BuildRecordV1, type OrchestrationStateSource, type NarratedSource, type PhaseCloseSource, type BuildRecordSources, } from './types.js';
 export { isValidPhaseIdentity, assertValidPhaseIdentity, InvalidPhaseIdentityError, renderPhaseSegment, type PhaseIdentity, } from '@halfcycle/events';
-export { MissingSourceError, projectSeedGuards, readGuardEvalLog, readOrchestrationState, readPhaseClose, validateNarrated, loadSources, } from './sources.js';
-export { BUILD_RECORD_ZONE_B_DIR, CLOSE_RECORD_FORMAT, InvalidCloseRecordError, closeRecordPath, parseCloseRecord, writeCloseRecord, type CloseRecordOutcome, type PhaseCloseRecord, } from './close-record.js';
-export { assembleBuildRecord, deriveTasks, deriveThesisHeld, deriveInvariantsExercised, } from './assemble.js';
-export { renderBuildRecordMarkdown } from './template.js';
-export { BUILD_RECORD_DIR, serialiseRecordJson, writeBuildRecord, type WriteResult, } from './write.js';
-import { type WriteResult } from './write.js';
-import type { NarratedSource } from './types.js';
-import type { PhaseIdentity } from '@halfcycle/events';
-/**
- * Assemble + write the Build Record for a phase from its local artefacts.
- *
- * Idempotent (INV-009): a deterministic function of the current artefacts —
- * re-running overwrites the pair with the same bytes if the inputs are
- * unchanged. Fails loud (throws `MissingSourceError`) if any required source is
- * absent — never blanks or invents a field.
- */
-export declare function assemblePhaseBuildRecord(opts: {
-    repoRoot: string;
-    phasesDir: string;
-    guardEvalLogDir: string;
-    phaseId: PhaseIdentity;
-    narrated: NarratedSource;
-    touchedInvariants: string[];
-}): WriteResult;
+export { renderBuildRecordV2Markdown } from './render-v2.js';
+export { BUILD_RECORD_DIR, NODE_RECORD_PAIR_IO, serialiseServedRecord, writeRecordPair, type RecordPairIo, type RecordPairResult, } from './write.js';
+export { REFUSAL_FOLLOW_UP, REFUSAL_REASONS, buildRecordUrl, obtainBuildRecord, refetchCommand, type ObtainOutcome, } from './obtain.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/build-record/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/build-record/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,KAAK,EACV,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,cAAc,EACd,gBAAgB,EAChB,WAAW,GACZ,MAAM,cAAc,CAAC;AAItB,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,cAAc,CAAC;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B,GAAG,WAAW,CAWd"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/build-record/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,EACL,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,kBAAkB,EAClB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAIpB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,cAAc,EACd,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/build-record/obtain.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Fetch a closed phase's Build Record from the Halfcycle service and write the pair
+ * into the client's repository — the one path both `close-phase` (after a close)
+ * and `build-record <phase>` (the re-fetch) take, so the two cannot drift.
+ *
+ * ONE RESPONSE-HANDLING RULE. A body that parses under `phaseRecordResponseSchema`
+ * is authoritative, whatever its status. Otherwise a 404 whose body is the
+ * service's own missing-route answer (`error: 'Not Found'`, `Route GET … not
+ * found.`) means the service predates Build Records. Anything else — including the
+ * route's own 404 for an engagement that is gone — is reported by its status and
+ * the service's own sentence, never reworded as a missing route.
+ *
+ * THE PATH IS THE PHASE ARGUMENT'S (INV-023). The served `phase` is compared with
+ * the one asked for and a mismatch writes nothing; the writer then builds its path
+ * from the argument alone.
+ *
+ * WHAT IS WRITTEN IS WHAT ARRIVED (INV-007). The `.json` is the served record as
+ * `JSON.parse` returned it, key order included — not the schema's output, which
+ * would reorder keys. The schema parse decides only whether it is written at all.
+ *
+ * INV-001: Node builtins, the global `fetch` and `@halfcycle/events` only.
+ * SHIPS TO CLIENT DISK inside the CLI: every string here is a client-facing
+ * sentence, and no comment sits beside an object member.
+ */
+import { type PhaseRecordRefusalReason } from '@halfcycle/events';
+import type { RepoCredential } from '../open-phase.js';
+import { type RecordPairIo } from './write.js';
+/**
+ * What came of asking for a phase's record. `written`: the pair is on disk (paths
+ * relative to the repository). `exists`: a file this CLI will not replace is in the
+ * way; nothing was written. `withheld` and `refused`: the service's answer, with its
+ * own sentence. `unavailable`: the record could not be obtained, and `why` says so.
+ */
+export type ObtainOutcome = {
+    kind: 'written';
+    jsonPath: string;
+    mdPath: string;
+} | {
+    kind: 'exists';
+    path: string;
+} | {
+    kind: 'withheld';
+    message: string;
+} | {
+    kind: 'refused';
+    reason: PhaseRecordRefusalReason;
+    message: string;
+} | {
+    kind: 'unavailable';
+    why: string;
+};
+/**
+ * The line the CLI adds after the service's own refusal sentence, per reason. The
+ * key set is the reason enum's: the type refuses a missing key at build time, and
+ * `close-produces-the-record.test.ts` compares the keys with
+ * `phaseRecordRefusalReasonSchema.options` read from the schema.
+ */
+export declare const REFUSAL_FOLLOW_UP: {
+    readonly 'still-open': "Nothing was written. The record is produced when the phase closes.";
+    readonly reopened: "Nothing was written. A new record is produced when the phase closes again.";
+    readonly 'never-opened': "Nothing was written. Check the name: it must match the phase name exactly as it was opened.";
+    readonly 'never-closed': "Nothing was written.";
+    readonly 'closed-before-records': "Nothing was written.";
+};
+/** The reason enum's options, read from the schema, for the key-set check. */
+export declare const REFUSAL_REASONS: readonly PhaseRecordRefusalReason[];
+/** The address of a phase's record: the phase is one path segment, encoded once. */
+export declare function buildRecordUrl(credential: RepoCredential, phase: string): string;
+/**
+ * Ask the service for `phase`'s frozen record and, when it serves one, write the
+ * pair under `repoRoot`. Never throws: every way this can fail — the network, the
+ * service, a write — is an outcome the caller prints, because by the time this
+ * runs after a close the phase has already closed.
+ */
+export declare function obtainBuildRecord(credential: RepoCredential, repoRoot: string, phase: string, io?: RecordPairIo): Promise<ObtainOutcome>;
+/**
+ * How to fetch a phase's record later, as a line a person can paste: the phase is
+ * quoted for the shell unless it is plain letters, digits and `._+-`.
+ */
+export declare function refetchCommand(phase: string): string;
+//# sourceMappingURL=obtain.d.ts.map

package/dist/build-record/obtain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"obtain.d.ts","sourceRoot":"","sources":["../../src/build-record/obtain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAwC,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAErF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;CAM+B,CAAC;AAE9D,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAE,SAAS,wBAAwB,EAA2C,CAAC;AAE3G,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,UAAU,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKhF;AASD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,UAAU,EAAE,cAAc,EAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,EAAE,GAAE,YAAkC,GACrC,OAAO,CAAC,aAAa,CAAC,CA0ExB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD"}

package/dist/build-record/render-v2.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The v2 Build Record markdown renderer: a pure function from a parsed
+ * `halfcycle-build-record/v2` record to the markdown half of the pair.
+ *
+ * It owns every word a reader of the `.md` sees, and the rule that keeps the
+ * client's words and the phase name from forging the observed register. The two
+ * registers are told apart by position: everything Halfcycle's own systems
+ * recorded prints as plain lines under an "Observed by Halfcycle" label, and
+ * everything the client stated prints as quoted lines, and only quoted lines,
+ * under a "Stated by the client" label. No other quoted line exists.
+ *
+ * PURE. It reads no clock, environment or locale. Numbers are formatted with
+ * `String()`, never a locale-aware formatter; `closedAt` is reworded by text
+ * substitution, never through `Date`. It iterates only keys it names, keeps array
+ * order, and sorts closes by `sequence` only. The same record gives the same
+ * bytes, whatever key order a database hands back.
+ *
+ * IT DOES NOT PARSE. The caller parses the record first; the type here is the
+ * contract's own inferred type, imported as a type so nothing of the contract
+ * module is pulled into this file at runtime. The one cross-half rule it relies
+ * on — both halves describe the same closes, paired by `sequence` — it checks
+ * itself and throws on, because printing a close without its other half would
+ * put a blank where a statement belongs.
+ *
+ * EVERY STRING HERE SHIPS. The fixed prose is printed into the client's own
+ * repository, so it is written in client words and carries no internal
+ * vocabulary; the tests scan the emitted markdown, not this source. No comment
+ * here sits beside an object member, because the bundler keeps those verbatim.
+ */
+import type { BuildRecordV2 } from '@halfcycle/events';
+/**
+ * Print one string from the record as inert, visible markdown text.
+ *
+ * Per code point: a hidden character becomes `U+` and its code in uppercase hex,
+ * at least four digits; a markdown special character is escaped with a
+ * backslash; everything else prints as itself. An empty string prints
+ * `(blank)`, so a slot is never silently empty.
+ */
+export declare function printRecordText(text: string): string;
+/**
+ * Render a parsed v2 Build Record as markdown.
+ *
+ * Throws, in client words, if the two halves describe different closes — which a
+ * parsed record cannot do. Output uses `\n` only and ends in exactly one `\n`.
+ */
+export declare function renderBuildRecordV2Markdown(record: BuildRecordV2): string;
+//# sourceMappingURL=render-v2.d.ts.map

package/dist/build-record/render-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-v2.d.ts","sourceRoot":"","sources":["../../src/build-record/render-v2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAyBvD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAapD;AAoQD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAyDzE"}

package/dist/build-record/write.d.ts

@@ -1,70 +1,38 @@
 /**
- * Write-disciplined Build-Record writer.
+ * The Build Record pair writer — what a close and the re-fetch write.
  *
- * Blast radius: the writer touches ONLY `docs/build-records/` in the target
- * repo (same write-discipline as the bundle installer, E1-T-06), and now
- * enforces it rather than claiming it (INV-023).
+ * Blast radius: the writer touches ONLY `docs/build-records/` in the target repo,
+ * the one path `WRITE_ALLOWLIST` gives the Build Record (INV-019), and it enforces
+ * that rather than claiming it (INV-023).
  *
- * THE RESIDUAL CHECK, AND WHY IT IS NOT DEFENCE IN DEPTH. The identity is
- * validated where every caller converges (`validateNarrated`), but
- * `assembleBuildRecord` and `writeBuildRecord` are exported individually too, so
- * a library caller can compose them without entering `loadSources` at all. For
- * that caller the assertion below is the ONLY guard.
+ * THE PATH COMES FROM THE CALLER'S PHASE ARGUMENT, never from the record. The
+ * identity is decided by `isValidPhaseIdentity`, which has one home in
+ * `@halfcycle/events`; the segment is `renderPhaseSegment`'s, from the same home.
+ * This module restates neither rule.
  *
- * It asserts on the joined OUTPUT PATH, not on the output directory. The
- * directory is a constant and the filename is the caller-influenced half, so a
- * directory comparison guards the half that was never at risk — which is exactly
- * how this function's previous check came to compare a value with itself and
- * refuse nothing. The two operands here are genuinely different: `outDir` is
- * derived from `repoRoot` and a constant and does not move when the record
- * changes, while the candidate path is derived from `record.phase.id` and moves
- * with every record.
- *
- * WHAT REFUSES FIRST CHANGED WHEN THE FILENAME MOVED TO THE RENDERER, and saying
- * so is better than leaving a reader to discover it. The residual refusal for a
- * library caller is now the `isValidPhaseIdentity` check in `writeBuildRecord`
- * below, which throws `InvalidPhaseIdentityError` naming this module's allowed
- * location — same error and same message a caller entering through
- * `validateNarrated` gets. `assertInsideOutDir` still runs on every write, but it
- * can no longer be the thing that fires on a hostile identity, because a hostile
- * identity never reaches the join: the identity check refuses it and the renderer
- * refuses it again.
- *
- * SO THE RESIDUAL GUARD IS UNREACHABLE FROM THIS PACKAGE, and that is measured
- * rather than assumed: deleting both of its call sites leaves this package's
- * whole suite green, and sixteen adversarial identities that pass the predicate
- * were probed without one reaching it. What it still guards is real and it is
- * CROSS-PACKAGE — the RENDERER'S OUTPUT. Every segment the renderer emits today
- * is a plain basename, so an edit in `packages/events` that let a separator into
- * one is the only way this can fire, and that edit is invisible from here. A
- * guard whose subject lives in another package cannot be exercised by a
- * behavioural test of this one, so it is exported and tested directly rather
- * than left module-private, where nothing could reach it and nothing would
- * notice its deletion.
- *
- * Refusal is ALL-OR-NOTHING because both paths are asserted BEFORE the first
- * `writeFileSync` — and before the `mkdirSync`, so a refused record does not
- * leave an empty directory behind either. There is no rollback and no two-phase
- * commit; nothing here asks for one.
+ * THE RESIDUAL CHECK, AND WHY IT IS EXPORTED. `assertInsideOutDir` runs on every
+ * path, temporary ones included, and compares two operands that move
+ * independently: the allowed directory (from `repoRoot` and a constant) and the
+ * candidate path (from the phase). A hostile phase never reaches it — the
+ * identity check refuses first and the renderer refuses again — so what it still
+ * guards is CROSS-PACKAGE: a rendered segment that grew a separator, which only an
+ * edit in `packages/events` could produce and which no behavioural test of this
+ * package can arrange. It is therefore exported and called directly by
+ * `build-record-write-discipline.test.ts`, the only control that can tell it
+ * from a deleted one.
  *
- * The JSON is serialised with a stable 2-space indent + trailing newline; the
- * markdown data slots are projected from the same record object, so the pair
- * cannot disagree on data.
+ * Refusal is ALL-OR-NOTHING: every path is asserted, and both texts are rendered,
+ * before the `mkdirSync` and the first create, so a refused record leaves no file
+ * and no empty directory behind.
  */
-import type { BuildRecordV1 } from './types.js';
+import { type BuildRecordV2 } from '@halfcycle/events';
 /** The one and only output directory (relative to the target repo root). */
 export declare const BUILD_RECORD_DIR: string;
-export interface WriteResult {
-    jsonPath: string;
-    mdPath: string;
-}
-/** Serialise the record JSON deterministically (2-space indent + trailing NL). */
-export declare function serialiseRecordJson(record: BuildRecordV1): string;
 /**
  * Assert that a joined output path is still a plain file directly inside
  * `outDir`. `relative` is computed between two values that move independently —
- * the allowed directory, and a candidate path built from the record — so this
- * comparison can actually fail.
+ * the allowed directory, and a candidate path built from the caller's phase — so
+ * this comparison can actually fail.
  *
  * EXPORTED SO IT CAN BE TESTED AT ALL. Its subject is a filename segment that
  * grew a separator, which only an edit in another package can produce, so no
@@ -75,9 +43,58 @@ export declare function serialiseRecordJson(record: BuildRecordV1): string;
  */
 export declare function assertInsideOutDir(outDir: string, candidate: string, identity: unknown): void;
 /**
- * Write the `.json` + `.md` pair for a phase into `docs/build-records/`.
- * Refuses — writing nothing at all — if the record's identity would put either
- * file anywhere else.
+ * The file operations `writeRecordPair` makes, behind one seam so a test can make
+ * the SECOND write fail and watch the first come back out. `createExclusive` opens
+ * with `wx` (never truncates an existing file) and removes what it created if the
+ * write itself fails; `rename` replaces in one step on the same filesystem.
+ */
+export interface RecordPairIo {
+    createExclusive(path: string, text: string): void;
+    rename(from: string, to: string): void;
+}
+export declare const NODE_RECORD_PAIR_IO: RecordPairIo;
+/**
+ * What `writeRecordPair` did. `created`: neither file existed. `up-to-date`: the
+ * `.json` already held these exact bytes, and the `.md` was rendered again.
+ * `replaced`: an earlier record of this same phase was replaced. `in-the-way`:
+ * a file this CLI did not write, or cannot recognise as this phase's earlier
+ * record, is at one of the two paths — nothing was written and `path` names it.
+ */
+export type RecordPairResult = {
+    kind: 'created' | 'up-to-date' | 'replaced';
+    jsonPath: string;
+    mdPath: string;
+} | {
+    kind: 'in-the-way';
+    path: string;
+};
+/** Serialise a served record for the `.json`: 2-space indent, trailing newline. */
+export declare function serialiseServedRecord(rawRecord: unknown): string;
+/**
+ * Write a phase's Build Record pair into `docs/build-records/`: the `.json` as the
+ * service sent it, and the `.md` rendered from the parsed record.
+ *
+ * THE PATH COMES FROM `phase`, THE CALLER'S VALIDATED ARGUMENT, and never from
+ * `record.phase` (INV-023). The caller compares the two before it gets here; this
+ * function does not rely on that, so a record naming `../../x` still lands at the
+ * argument's path.
+ *
+ * EXCLUSIVE CREATE IS THE EXISTENCE CHECK. There is no separate look first, which
+ * would leave a window between looking and writing. `.json` is opened `wx`, then
+ * `.md`; on `EEXIST` from either, any `.json` this call created is removed and the
+ * replace check decides: (a) the same `.json` bytes — up to date, and the `.md` is
+ * rendered again so a renderer change never refuses the CLI's own pair; (b) this
+ * phase's own earlier record — both files are replaced; (c) anything else —
+ * nothing is written and the file in the way is named.
+ *
+ * NO HALF PAIR. A replace writes `<final name>.tmp` beside each file and renames
+ * it over the old one; if the second rename fails, the first file gets its old
+ * bytes back. A fresh create whose second file fails removes the first. Every
+ * path, temporary ones included, is checked to be a plain file directly inside
+ * the directory before anything is created.
+ *
+ * @throws InvalidPhaseIdentityError when `phase` cannot name a file.
+ * @throws the file system's own error when a write fails; nothing is left behind.
  */
-export declare function writeBuildRecord(repoRoot: string, record: BuildRecordV1): WriteResult;
+export declare function writeRecordPair(repoRoot: string, phase: string, rawRecord: unknown, record: BuildRecordV2, io?: RecordPairIo): RecordPairResult;
 //# sourceMappingURL=write.d.ts.map

package/dist/build-record/write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/build-record/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAE9D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAM7F;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,WAAW,CA2BrF"}
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/build-record/write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAcH,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAE3B,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAM7F;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAClD,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAsBD,eAAO,MAAM,mBAAmB,EAAE,YAGjC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,SAAS,GAAG,YAAY,GAAG,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjF;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzC,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAEhE;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,aAAa,EACrB,EAAE,GAAE,YAAkC,GACrC,gBAAgB,CAyDlB"}

package/dist/close-phase.d.ts

@@ -29,13 +29,40 @@
  *
  * INV-001: this file imports the global `fetch` (Node 20), Node builtins, and
  * `@halfcycle/events` — one of the exactly two workspace packages a shippable may
- * import. `acceptanceOutcomeSchema` is the ONE home for the outcome's shape
- * (INV-003), so the CLI validates what it builds against the same schema the route
- * parses with. It never imports the control service.
+ * import. `acceptPhaseRequestSchema` is the ONE home for the request's shape
+ * (INV-003), so the CLI validates the whole body it builds against the same schema
+ * the route parses with. It never imports the control service.
+ *
+ * SINCE CONNECT PHASE 4 (`close-produces-the-record`) the close carries the
+ * client's statements and the full commit it closed at, and writes no local close
+ * note. The service freezes both into the phase's Build Record; the caller fetches
+ * that record afterwards (`build-record/obtain.ts`).
  */
 import { type AcceptanceOutcome, type PhaseCloseDecision } from '@halfcycle/events';
 import { type PhaseStampFailure, type RepoCredential } from './open-phase.js';
-import { type CloseRecordOutcome } from './build-record/close-record.js';
+/**
+ * Whether the commit this phase closed at could be read, and if so the full hash
+ * that travelled with the close. When it could not, `reason` says why in words a
+ * developer can act on; the record shows the commit as not stated.
+ */
+export type CloseCommitOutcome = {
+    read: true;
+    commit: string;
+} | {
+    read: false;
+    reason: string;
+};
+/**
+ * The client's own words on a close: what the phase set out to prove, what came of
+ * it, and how the work departed from the plan. `null` / empty when not stated.
+ */
+export interface StatedStatements {
+    thesis: string | null;
+    outcome: string | null;
+    deviations: string[];
+}
+/** Nothing stated — what a close sends when no statement flag was given. */
+export declare const NO_STATEMENTS: StatedStatements;
 /** What `POST /engagements/:id/accept` returns on 200 (the fields the CLI reports). */
 export interface ClosedPhase {
     engagementId: string;
@@ -47,13 +74,20 @@ export interface ClosedPhase {
      * machine is still filed under a phase that is no longer open.
      */
     stampFailure: PhaseStampFailure | null;
-    /**
-     * Whether the commit this phase closed at was written down on this machine,
-     * and where. When it was not, this says why, and the phase's Build Record will
-     * say the commit and the close date were not recorded.
-     */
-    closeRecord: CloseRecordOutcome;
+    /** The commit sent with the close, or why none could be read. */
+    closeCommit: CloseCommitOutcome;
 }
+/**
+ * Read the full HEAD commit of the NAMED repository, before the close is sent.
+ *
+ * `gitEnvForNamedRepo` strips the variables that tell git which repository to use,
+ * so an absolute `GIT_DIR` inherited from a hook cannot substitute another
+ * repository's HEAD for this one's. git's own stderr is discarded: a failure here
+ * is expected, the close still goes ahead, and the caller says why in plain words.
+ * The hash is checked by the contract's own `closeCommitSchema`, so a short or
+ * malformed answer is never sent.
+ */
+export declare function readCloseCommit(repoRoot: string | undefined): CloseCommitOutcome;
 /**
  * A refusal from the control plane, carried as an error the CLI can print whole.
  *
@@ -108,6 +142,13 @@ export declare class ClosePhaseRefused extends Error {
      */
     code?: string | undefined);
 }
+/**
+ * A close refused on this machine, before anything was sent: the request failed the
+ * shared request schema. The CLI prints the message and exits as a usage error.
+ */
+export declare class CloseRequestInvalid extends Error {
+    constructor(message: string);
+}
 /**
  * Record a phase's acceptance and close it.
  *
@@ -118,16 +159,18 @@ export declare class ClosePhaseRefused extends Error {
  *                for the same reason `openPhase` requires its entry decision: there
  *                is no argument-less way to move the phase axis, so an unattributed
  *                close is unreachable from any caller that compiles.
- * @param repoRoot the repository whose commit this close is being recorded against.
+ * @param repoRoot the repository whose HEAD this close is sent with.
  *                Optional so that a caller with no repository in hand — a test
  *                harness, a future non-repo surface — is not forced to invent one;
- *                omitting it records no commit rather than silently resolving the
- *                process's working directory, which would write a stranger's HEAD
- *                into this phase's record.
+ *                omitting it sends no commit rather than silently resolving the
+ *                process's working directory, which would send a stranger's HEAD.
+ * @param stated  the client's own statements; each absent one is sent as not
+ *                stated (`null`, or no deviations).
  *
  * @throws ClosePhaseRefused on a 4xx the plane explained, so the CLI prints the
  *         plane's own sentence and exits non-zero.
- * @throws Error on transport failure or a body that is not the expected shape.
+ * @throws Error before anything is sent when the request fails the shared schema;
+ *         on transport failure; or on a body that is not the expected shape.
  */
-export declare function closePhase(credential: RepoCredential, phase: string, outcome: AcceptanceOutcome, close: PhaseCloseDecision, home?: string, repoRoot?: string): Promise<ClosedPhase>;
+export declare function closePhase(credential: RepoCredential, phase: string, outcome: AcceptanceOutcome, close: PhaseCloseDecision, home?: string, repoRoot?: string, stated?: StatedStatements): Promise<ClosedPhase>;
 //# sourceMappingURL=close-phase.d.ts.map

package/dist/close-phase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"close-phase.d.ts","sourceRoot":"","sources":["../src/close-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC/F,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAE3F,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC;;;;OAIG;IACH,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,MAAM,EAAE,MAAM;IAE9B;;;;;OAKG;aACa,OAAO,CAAC,EAAE,MAAM;IAChC;;;;;;;;;;OAUG;aACa,IAAI,CAAC,EAAE,MAAM;gBApBb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;IACf;;;;;OAKG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA;IAChC;;;;;;;;;;OAUG;IACa,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAwFtB"}
+{"version":3,"file":"close-phase.d.ts","sourceRoot":"","sources":["../src/close-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAGH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAmB,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG/F;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,4EAA4E;AAC5E,eAAO,MAAM,aAAa,EAAE,gBAAkE,CAAC;AAE/F,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,iEAAiE;IACjE,WAAW,EAAE,kBAAkB,CAAC;CACjC;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,kBAAkB,CA4BhF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,MAAM,EAAE,MAAM;IAE9B;;;;;OAKG;aACa,OAAO,CAAC,EAAE,MAAM;IAChC;;;;;;;;;;OAUG;aACa,IAAI,CAAC,EAAE,MAAM;gBApBb,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM;IACf;;;;;OAKG;IACa,OAAO,CAAC,EAAE,MAAM,YAAA;IAChC;;;;;;;;;;OAUG;IACa,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,MAAM,EACb,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,GAAE,gBAAgC,GACvC,OAAO,CAAC,WAAW,CAAC,CAyEtB"}