Editor Refinement with FORAY Audit Substrate

Add a version-string scanning module at functions/api/_version_scanner.ts. The module exports two functions:

• scanForVersionReferences(content: string, oldVersion: {major: number, minor: number}): VersionMatch[] — walks the content and returns matches in order of appearance.
• applyApprovedSubstitutions(content: string, approvals: ApprovalRecord[]): string — applies operator-approved substitutions atomically, returns transformed content.

The VersionMatch type carries: { lineNumber: number, lineText: string, contextBefore: string[], contextAfter: string[], matchedText: string, proposedReplacement: string, patternFamily: "A" | "B" | "C" | "D" | "E" | "F", confidence: "high" | "medium" | "low" }. Pattern A/B/C matches return confidence "high"; D/E return "medium"; F returns "low" (cross-document references should default to declined).

Define scanner pattern recognition. The scanner walks the content line by line. For each line, it checks pattern families in order:

• Pattern A: regex matching <title> elements containing v\d+\.\d+. Match if the version found equals the old version.
• Pattern B: regex matching <div class="doc-version-line"> or <div class="doc-meta"> or sidebar-subtitle elements containing the old version.
• Pattern C: regex matching <p> elements in the trailing third of the document containing the old version. (Footers are typically the last paragraph; using "trailing third" rather than "last paragraph" gives the scanner robustness to multi-paragraph footers.)
• Pattern D: regex matching prose forms like "from v\d+\.\d+", "supersedes v\d+\.\d+", "v\d+\.\d+ to v\d+\.\d+". Returns medium confidence — operator must judge whether the reference is to the document being bumped or to historical predecessors.
• Pattern E: regex matching arrow notation (v0.1 → v0.2) and underscore filename form (v0_1, v0_2) where the value matches the old version.
• Pattern F: regex matching cross-document filename references — anything matching name-v\d+_\d+\.html or name-v\d+_\d+\.md where name differs from the document's own base filename. Low confidence — should default to declined unless operator approves.

Modify functions/api/save.ts to invoke the scanner during version-bump. Between line 152 (after currentContent is fetched) and line 161 (before githubMultiFileCommit):

1. Call scanForVersionReferences(body.content, {major: parsed.major, minor: parsed.minor}).
2. If matches are returned and no body.approvals field is present in the request: return a 422 response with the matches array and a request to the client for approval. The client (editor.js) will present the approval UI and re-submit with body.approvals.
3. If body.approvals is present: call applyApprovedSubstitutions(body.content, body.approvals) and write the result to newPath.

This two-step protocol keeps the Pages Function stateless while letting the client present the approval UI. The first POST sends content with no approvals field; the server scans and returns matches; the client presents the UI; the second POST sends the same content with approvals field populated; the server applies the approvals and proceeds with the commit.

Modify tools/static/editor.js to handle the 422 approval-required response. When saveDocument(payload) receives a 422 with a matches array:

1. Dismiss the saving-status indicator.
2. Present an approval UI inside the editor modal (or as a sub-modal). The UI shows each match with its line number, surrounding context, matched text, proposed replacement, and pattern-family designation.
3. Each match has Approve / Decline buttons. High-confidence matches default to Approve; low-confidence (Pattern F) defaults to Decline; medium-confidence is undefaulted (operator must choose).
4. An "Approve all high-confidence" button is provided for fast handling when the operator trusts the scanner's classification.
5. When the operator confirms, re-submit the save request with the approvals field populated as [{ matchIndex: number, decision: "approve" | "decline" }].

Modify tools/static/editor.js at the success-handling branch of saveDocument (after line 184, before line 187). When payload.mode === "version-bump" and the save succeeded:

1. Show the success status briefly (1-2 seconds).
2. Close the current editor modal.
3. Call openEditFlow(json.newPath) to reopen the editor against the new versioned path.
4. The reopened editor will perform a fresh GET /api/document?path=... against the new path, picking up the just-written content and the new file's sha.

Additionally: dispatch a history.replaceState call to update the URL bar's path component to the new versioned filename, so the browser's URL reflects the document the operator is now editing.

Update the modal's "Saved" status message to reflect the new behavior. Current message says "Saved as new version. Commit X. New path: Y. Previous archived." Change to "Saved as v0.N. The editor is reopening at the new version." (with the actual version number interpolated).

Rework the two save actions in the editor modal's footer. The current "Save (Minor Correction)" and "Save as New Version" buttons share visual weight. Change to:

• Primary action: Save as v0.N (with the new version number interpolated; e.g. "Save as v0.4" when bumping from v0.3). Treated as the primary action — solid background, more prominent. The verb "Save" appears with the destination version, so the consequence is visible without parsing.
• Secondary action: Correct in place. Treated as secondary — outlined, less prominent. The phrase "Correct in place" reads as a smaller intent than "Save as v0.N" and signals that no new version is created.

The visual hierarchy matches the cognitive hierarchy: bumping versions is the substantive action; correcting in place is the smaller action.

Update the corresponding CSS in tools/static/editor.css (or equivalent stylesheet for the editor modal). Primary action: solid press-ink background, white text, 600 font-weight. Secondary action: 2px iron-oxide border, transparent background, iron-oxide text. Both follow the letterpress palette already established in the brand reference.

End-to-end manual verification by the Operator. The Operator performs a real version-bump on a real document (a low-stakes document, such as a scratch document created for this purpose, rather than the architecture spec itself). Walks through: open the document; modify content; click "Save as v0.N"; review the scanner's approval surface; approve appropriately; confirm the new version lands; confirm the editor reopens at the new path; confirm the URL updates. Reports back any friction observed.

Add the event-type constant. In src/loomworks/audit/events.py, add a new constant alongside the existing EVENT_TYPE_SETTING_CHANGE at line 31:

EVENT_TYPE_EDITOR_COMMIT = "editor_commit"

Export the constant from the module's __init__.py alongside the existing exports.

Add the writer helper at src/loomworks/audit/events.py, immediately following write_setting_change_event. The signature follows the existing pattern:

async def write_editor_commit_event(
    *,
    actor_person_id: UUID,
    document_path: str,
    prior_content_hash: str | None,
    new_content_hash: str,
    commit_message: str,
    commit_sha: str,
    db: AsyncSession,
    now: datetime | None = None,
) -> UUID:

Body constructs an AuditForayEventRow with event_type=EVENT_TYPE_EDITOR_COMMIT, actor_person_id as supplied, engagement_id=None (editor commits are not engagement-scoped today; see Open-2.1), and a payload of {"document_path": ..., "prior_content_hash": ..., "new_content_hash": ..., "commit_message": ..., "commit_sha": ...} coerced through _json_safe. tx_id = uuid.uuid4() following F0.2. Awaits db.flush(). Returns the tx_id.

Write unit tests for the new writer at tests/audit/test_editor_commit_event.py. Tests should follow the pattern established in tests/audit/ for the setting-change writer if such tests exist; otherwise establish the pattern. Specifically: a happy-path test that constructs a row and verifies persistence; a JSON-safety test verifying non-encodable payload values are coerced via _json_safe; an error-path test verifying SQLAlchemyError propagates (the caller is responsible for catching, per A.5).

Add a new router at src/loomworks/api/routers/audit_editor_commit.py. The router exposes one endpoint:

POST /audit/editor-commit
  Body: {
    actor_person_id: UUID,
    document_path: str,
    prior_content_hash: str | None,
    new_content_hash: str,
    commit_message: str,
    commit_sha: str,
  }
  Response (200): { tx_id: UUID }
  Response (401): if service token missing or invalid
  Response (422): if validation fails

The endpoint is protected by the service-token authentication established in Piece 3 (Section 3.A, S3.1-S3.4). It validates the body via a Pydantic request model, calls write_editor_commit_event, and returns the resulting tx_id.

Register the router in src/loomworks/api/app.py within _register_routers(app). Place alongside other audit/admin routers, following the existing registration pattern.

Modify functions/api/save.ts to call the engine audit endpoint after every successful commit. The call happens after githubMultiFileCommit(...) returns successfully and before the response is returned to the client. In both code paths (version-bump path lines 161-170 and minor-correction path elsewhere in the file):

1. Compute the new content hash using SHA-256 of the canonical JSON-serialized content (or just SHA-256 of the raw content; the CR proposes raw content as simpler).
2. Compute the prior content hash from currentContent.content (in the version-bump path) or by fetching the prior version via the GitHub API (in the minor-correction path, where the prior content was just overwritten).
3. Call the engine endpoint POST /audit/editor-commit with the operator UUID (resolved at session start per Piece 3), the document path, the prior and new content hashes, the commit message, and the commit SHA returned from GitHub.
4. Wrap the call in try/catch. On failure, log to Cloudflare logs and continue — the commit is authoritative; the audit row is best-effort per A.5. The Pages Function returns success to the client regardless of audit-write outcome.

Add a helper in functions/api/_shared.ts for the audit-emit call. async function emitEditorCommitAudit(env, payload) takes the Pages Function's env object (for the service token and engine base URL) and the payload, performs the POST, returns the tx_id on success or throws on failure. The caller in save.ts wraps the call in try/catch.

Add Cloudflare Pages secrets. Two new environment variables on the Cloudflare Pages project for record.dunin7.com:

• LOOMWORKS_ENGINE_BASE_URL — the production URL of the engine (e.g. https://api.loomworks.doneinseven.com). Set per A.6's deferred resolution.
• LOOMWORKS_ENGINE_SERVICE_TOKEN — the service token from A.1.

This step is an operational task for the Operator, not CC: secrets are added through the Cloudflare dashboard rather than via code.

Verify engine is reachable from outside the M4. The Operator and CC together determine the engine's current production reachability. Specifically: attempt to curl the engine's health endpoint (or any unauthenticated GET endpoint) from a host outside the M4's local network — e.g. from a Cloudflare Pages Function preview environment, or from Claude.ai's web fetch tool. Document the response.

Configure engine CORS. Add https://record.dunin7.com to the engine's LOOMWORKS_CORS_ORIGINS environment variable. Add Authorization to the allow_headers list in src/loomworks/api/app.py (the current list is ["Content-Type"] per F0.5; change to ["Content-Type", "Authorization"]). Engine restart required for env-var change; code change deploys via the engine's normal deployment path.

Add the service-token authentication dependency in src/loomworks/api/deps.py. New function require_service_token(authorization: str = Header(None)) that extracts the bearer token from the Authorization header, compares against settings.loomworks_engine_service_token (a new settings field), raises 401 on mismatch, returns nothing on match.

Settings field defined in src/loomworks/config.py alongside existing settings: loomworks_engine_service_token: str = "". Read from env var LOOMWORKS_ENGINE_SERVICE_TOKEN. If empty (not configured), the dependency rejects all requests (so the absence of a configured token can never accidentally allow unauthenticated access).

Write unit tests for the service-token dependency at tests/api/test_service_token_auth.py. Tests: dependency rejects missing token (401); rejects wrong token (401); accepts correct token (no exception). The test must configure loomworks_engine_service_token through the test fixtures, not from the actual env.

Add a router at src/loomworks/api/routers/persons_resolve.py with one endpoint:

POST /persons/resolve-email
  Body: { email: str }
  Response (200): { person_id: UUID, email: str }
  Response (404): if no person matches
  Response (401): if service token missing or invalid

The endpoint depends on require_service_token (S3.3). It calls get_person_by_email (F0.6) and returns the resulting UUID. Returns 404 if no match. Per F0.6 the substrate returns first-match-by-created_at on non-unique emails; the endpoint accepts this semantics per A.2.

Register the router in src/loomworks/api/app.py within _register_routers(app). Place alongside other person/identity routers.

Write unit tests at tests/api/test_persons_resolve.py. Tests: 401 on missing/wrong service token; 200 with correct token and matching email; 404 with correct token and non-matching email; first-match semantics verification (insert two persons with same email at different created_at, verify earlier one is returned).

Add a router at src/loomworks/api/routers/audit_read.py. The router exposes four endpoints:

GET /audit/events
  Query: ?limit=N (1-100, default 50), ?cursor=opaque,
         ?event_type=editor_commit (optional filter),
         ?actor_person_id=UUID (optional filter),
         ?since=ISO8601 (optional filter), ?until=ISO8601 (optional)
  Response: { events: [...], next_cursor: str | null }

GET /audit/events/{tx_id}
  Response: full event row by transaction id

GET /audit/events/by-document?document_path=...
  Query: same pagination as /audit/events
  Response: events filtered to a specific document_path
            (filters payload.document_path field for editor_commit events)

GET /audit/events/summary
  Response: counts grouped by event_type, by actor, by recent date buckets
            (used by the viewer's landing page)

All endpoints depend on require_service_token. All carry standard Pydantic response models. Pagination uses the opaque-cursor convention from F0.4: cursor is base64-URL JSON of {"ts": "<iso8601>", "id": "<uuid>"}, where ts is the row's timestamp and id is the row id for tiebreaking on simultaneous events.

Define the response models. A AuditEventResponse Pydantic model with fields matching the row schema (id, tx_id, event_type, actor_person_id, engagement_id, payload, timestamp). Signature field is intentionally omitted from the response — it's binary and not useful in JSON; if a future viewer needs it, a separate endpoint can expose it. AuditEventListResponse wraps a list of events plus next_cursor.

Implement cursor encoding/decoding helpers in src/loomworks/api/_audit_cursor.py. Two functions: encode_cursor(ts: datetime, id: UUID) -> str and decode_cursor(cursor: str) -> tuple[datetime, UUID]. Base64-URL JSON encoding per F0.4. Raise ValueError on malformed cursor.

Implement the query logic for each endpoint. GET /audit/events: build a SQLAlchemy select against AuditForayEventRow, apply optional filters (event_type, actor_person_id, since/until), apply cursor-based pagination ordering by (timestamp DESC, id DESC), limit to limit + 1 rows to detect "is there a next page", return up to limit events plus a next_cursor if a next page exists. The four indexes on the table (F0.7) cover the expected query shapes.

Implement the by-document filter. GET /audit/events/by-document filters on payload->>'document_path' = :document_path at the SQL level. Postgres JSONB operator. Combine with the other optional filters; combine with cursor pagination. Add an index on (payload->>'document_path', timestamp DESC) via a new alembic migration if the existing indexes don't cover this query (the four existing indexes F0.7 do not include a payload-keyed one).

Add the by-document index migration at migrations/versions/00XX_audit_payload_document_path_index.py (next available number). The migration creates a B-tree index on ((payload->>'document_path'), timestamp DESC). Reversible — the downgrade drops the index.

Implement the summary endpoint. GET /audit/events/summary returns three aggregations: counts by event_type (over all time); counts by actor_person_id (top 10 by event count); counts by date bucket (last 7 days, last 30 days, last 90 days, all time). Used by the viewer's landing page to give a quick overview before drilling into specifics.

Register the router in src/loomworks/api/app.py. Write unit tests at tests/api/test_audit_read.py covering: all four endpoints, all filter combinations, pagination correctness (cursor returns same results, next_cursor is null on last page), edge cases (empty result set, malformed cursor returns 422).

Add a helper in functions/api/_shared.ts for UUID resolution. async function resolveOperatorUUID(env, email): Promise<string> calls the engine's POST /persons/resolve-email endpoint with the service token, returns the person UUID on 200, throws on 404 or 401.

Add a session-init endpoint at functions/api/session-init.ts exposed at GET /api/session-init. The endpoint authenticates the Cloudflare Access email (per F0.6's mechanism), calls resolveOperatorUUID(env, email), returns the UUID to the client. The editor calls this endpoint once when first loaded.

Modify tools/static/editor.js to call /api/session-init at editor load and cache the returned UUID in a module-level variable. The cached UUID is included in subsequent POST /api/save calls. If session-init fails (engine unreachable, email unresolvable), the editor displays a warning at the top of the modal — commits will still proceed but audit rows will fail. This matches A.5's best-effort discipline.

Add an audit-viewer section to the record.dunin7.com static-site build. In tools/build_site.py, add a new section entry ("audit", "Audit", "FORAY narrative events...") following the existing pattern. The section gets a card on the landing page like the others.

Add the audit-viewer page at audit/index.html. The page is a single-page client-rendered viewer. Initial load shows the summary endpoint's response (counts by event type, top actors, date buckets). The page has three primary views:

• Default view (newest-first list): a paginated list of events showing event type, actor, timestamp, document path (for editor_commit events), and a link to a per-event detail page.
• Filtered view: top-of-page controls let the operator filter by date range, by actor UUID, by document path. Filters compose; URL parameters reflect the filter state so the operator can share a filtered link.
• Per-document view: reachable via audit/?document_path=.... Shows events filtered to one document. Linked from each document's own viewer page (S3.21).

Add per-document audit links. In tools/build_site.py, modify the document-viewer template to include a small "View audit history" link in the document's chrome (next to the breadcrumb or in a sidebar). The link routes to /audit/?document_path=<path>.

Write the audit-viewer client JS at tools/static/audit-viewer.js. Plain vanilla JS, no framework — matches the existing tools/static/ idiom. Calls the engine's audit-read endpoints (via the Pages Function as a proxy, see S3.23). Renders events into a templated list. Handles cursor pagination via "Load more" button. Renders filter controls and propagates changes to URL params.

Add a Pages Function proxy for audit reads at functions/api/audit.ts. The proxy receives requests from the audit-viewer client, adds the service-token Authorization header, forwards to the engine's audit endpoints, returns the response. The client never sees the service token; the token never leaves the Pages Function environment.

Routes proxied: /api/audit/events, /api/audit/events/:tx_id, /api/audit/events/by-document, /api/audit/events/summary. Query parameters and cursors pass through unchanged.

Add CSS for the audit viewer matching the letterpress palette. Event entries use vellum background with brass left-border; event_type badge uses iron-oxide tint matching the FORAY-event identity. Filter controls follow the existing scoping-notes-section visual pattern. Page layout matches the project's standard three-region structure (header, main, footer).

Verify all acceptance gates. Walk G1.1 through G3.6 in order. For each gate, confirm the gate holds with the corresponding test passing. Any gate that does not hold becomes a close-blocker; either the gate is met (further work) or the gate is explicitly deferred with rationale (re-scope decision).

Produce implementation notes. File phases/phase-63-editor-refinement/loomworks-phase-63-implementation-notes-v0_1.md in the loomworks-record repository. Notes cover: what landed, what was deferred and why, any open questions remaining, any methodology contributions surfaced during execution, any boundary cases observed in the visual classification system that warrant systemwide refinement.

Tag both repositories at phase-63-editor-refinement-with-foray-audit. The tag points at the engine commit and the loomworks-record commit that together constitute the Phase 63 ship. If the engine and loomworks-record need different tags (e.g. record.dunin7.com lands first while engine work is being verified), each repo gets its tag at its own commit; the implementation notes document both SHAs.

Trigger manifest absorption. Open a separate session for the v0.41 → v0.42 manifest absorption. The absorption includes Phase 63 plus the still-deferred Phase 57 close-out plus the eleven-phase methodology candidate backlog. Manifest absorption is its own scope and is not absorbed into Phase 63's close.