@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-batch5-runtime-intent-contract-promotion.md

@@ -0,0 +1,535 @@
+# v0.9 Batch 5 Report: Runtime Intent and Contract Promotion
+
+## 1. VERDICT
+
+PASS_V0_9_BATCH5_RUNTIME_INTENT_CONTRACT_PROMOTION
+
+## 2. Repository identity
+
+1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
+2. Branch: `master`
+3. Starting HEAD: `194c8e3df49017e803c2b99c6cad7d7c7cd69508`
+4. Ending HEAD before the final commit: `194c8e3df49017e803c2b99c6cad7d7c7cd69508`
+5. Package version: `0.8.1` (unchanged in `package.json` and `package-lock.json`)
+6. Viewer protocol version: `1.2.0` (was `1.1.0`)
+
+## 3. Prompt 4 entry gate
+
+1. Prompt 4 verdict: `PASS_V0_9_BATCH4_EXTERNAL_REFERENCE_ANNOTATION_AUTHORING`
+2. Prompt 4 commit: `194c8e3df49017e803c2b99c6cad7d7c7cd69508`
+3. Viewer protocol at entry: `1.1.0`
+4. Annotation schema: `1.0.0` (unchanged)
+5. Frontend contract schema: `1.0.0` (unchanged)
+6. Preflight found a clean tracked worktree on `master` at the required HEAD.
+7. `git ls-files -v docs/reports/v0.9-architecture-retrieval.md` printed `S`
+   at entry and before commit. The `skip-worktree` state was preserved and
+   the file was not restored, overwritten, or committed. No pull, rebase,
+   reset, or clean was run.
+
+## 4. Runtime intent vocabulary
+
+1. New pure model `viewer/src/annotation/runtimeIntent.ts` builds only the
+   already-frozen runtime `VisualAnnotationIntent`.
+2. Operations are exactly `inspect`, `move`, `resize`, `remove`, `preserve`.
+3. Categories are exactly `requested`, `expected-dependent`, `protected`, and
+   `preserved`.
+   1. `unexpected` is never offered.
+   2. If `unexpected` is supplied anyway, construction refuses it
+      (unit-tested).
+   3. The domain validator is unchanged.
+4. `expected-dependent` requires `required` or `permitted`. For every other
+   category the mode is absent.
+5. The model never reads mark geometry, never calls an API, and never
+   persists or evaluates anything.
+
+## 5. Move mappings
+
+Move requires an explicit `runtime-target` association.
+
+1. `right` maps to `property-increases x`.
+2. `left` maps to `property-decreases x`.
+3. `down` maps to `property-increases y`.
+4. `up` maps to `property-decreases y`.
+
+`minimumDeltaPx` is never set. Arrow direction and drawing position never
+choose the direction. This is browser-verified: an arrow drawn pointing right
+stays `uninterpreted`, and an explicit "move left" gives
+`property-decreases header.x`.
+
+## 6. Resize mappings
+
+Resize requires an explicit `runtime-target` association.
+
+1. `wider` maps to `property-increases width`.
+2. `narrower` maps to `property-decreases width`.
+3. `taller` maps to `property-increases height`.
+4. `shorter` maps to `property-decreases height`.
+
+`minimumDeltaPx` is never set.
+
+## 7. Preserve mappings
+
+1. With a `runtime-target` association, the user picks one property (`x`,
+   `y`, `width`, `height`) and a contract tolerance (`exact`, `absolute-px`,
+   or `percent`, amount between 0 and 100). The result is
+   `property-unchanged-within-tolerance`.
+2. `absolute-px` is labeled "runtime CSS pixels". It is kept distinct from
+   the reference vocabulary's `absolute-reference-px`.
+3. With a `runtime-relationship` association, the result is
+   `relationship-unchanged` with the association's `relationshipKind`, and
+   with `subjectTarget` and `relatedTarget` only when present. Page-level
+   relationships get no invented targets.
+4. No preserve UI exists for visibility, clipping, scroll, document width,
+   bounds, fit, overlap, or relative width.
+
+## 8. Remove unsupported behavior
+
+1. `remove` requires a target association and has no `contractPrimitive`.
+2. Once confirmed, the UI shows exactly: "Confirmed but not canonically
+   promotable: the current frontend-contract vocabulary has no target-absent
+   primitive."
+3. Its promotion checkbox is disabled with that reason.
+4. A forced API promotion returns 422 and writes no contract
+   (browser-verified).
+
+## 9. Inspect informational behavior
+
+1. `inspect` can be bound or unbound.
+2. It can be a candidate and then confirmed.
+3. It is never listed for promotion.
+4. A forced API promotion returns 422 (browser-verified).
+
+## 10. Runtime confirmation workflow
+
+1. "Set candidate intent" sets `{ state: 'candidate', intent }` only after
+   the form is complete and the association is compatible.
+2. When the item is unbound, the UI shows "Select and explicitly associate a
+   runtime target or relationship first." and the button stays disabled.
+3. The selected item shows the exact intent as JSON: operation, category,
+   mode, and primitive.
+4. The item also shows a promotion status line.
+5. "Confirm runtime intent" is enabled only for a candidate. It sets
+   `confirmed` with a new `confirmedAt`.
+6. Nothing confirms automatically: not selecting an intent, association,
+   drawing, Save, or the promotion checkbox.
+7. The shared helper `viewer/src/annotation/confirmation.ts` now holds
+   `confirmCandidate` and `withdrawChangedConfirmation`. The code moved there
+   unchanged from `referenceIntent.ts`, which still re-exports
+   `confirmCandidate`. The Prompt 4 unit and browser tests pass unchanged.
+
+## 11. Confirmation invalidation
+
+1. `useRuntimeAnnotationDraft` now routes every edit through
+   `applyRuntimeItemEdit`: reconcile, then withdraw a changed confirmation.
+   Edits here are mark moves, note text, association set or clear, and new
+   intents.
+2. Reconciliation:
+   1. A target change retargets `primitive.target`.
+   2. A relationship change rewrites the `relationship-unchanged` primitive.
+   3. An incompatible association, or clearing it, sets the change
+      interpretation back to `uninterpreted`. It is never coerced.
+3. A confirmed item whose mark, association, or intent changes goes back to
+   `candidate` without `confirmedAt`. A no-op edit keeps confirmation.
+4. Browser-verified: changing a confirmed move from `header` to `footer`
+   gives `primitive.target: footer` and state candidate. Reconfirmation
+   works. Moving the mark again gives candidate.
+
+## 12. Promotable-item rules
+
+An item is promotable only when all of these hold:
+
+1. It is `confirmed`.
+2. `intent.kind` is `change`.
+3. The operation is `move`, `resize`, or `preserve`.
+4. A valid `contractPrimitive` is present, checked with the existing
+   `isValidContractPrimitive`.
+5. A runtime association is present.
+6. The primitive matches both the association and the operation:
+   1. `move` uses `x` or `y`; `resize` uses `width` or `height`.
+   2. Both use increases or decreases on the associated target, with no
+      `minimumDeltaPx`.
+   3. Preserve on a target uses a property primitive on that target.
+   4. Preserve on a relationship uses exactly that relationship.
+
+Uninterpreted, candidate, inspect, remove, missing-primitive, unbound, and
+mismatched items are not promotable. The viewer's `runtimePromotionStatus`
+drives presentation only. The server repeats every check.
+
+## 13. Annotation-to-contract application service
+
+New `src/application/visualAnnotationContractPromotionService.ts`,
+`promoteVisualAnnotationContract(options)`:
+
+1. Validates the annotation with the canonical `isValidVisualAnnotationArtifact`.
+2. Requires a `runtime-observation` source. Anything else is
+   `unsupported-source`.
+3. Requires the supplied observation to exactly match the source.
+   Otherwise it is `source-mismatch`. The fields compared are
+   `observationId`, `requestId`, schema version, screenshot recorded and path
+   equal, and viewport width and height.
+4. Rejects the whole promotion (`invalid-selection`, nothing written) for any
+   of these: empty, more than 100, duplicate, unknown, or any non-promotable
+   selected item. It never writes a partial contract.
+5. Clause order follows `selectedItemIds` exactly.
+6. Persists exactly once through `persistPerChangeContract`, which is
+   unit-verified with a spy.
+7. The result is a discriminated union with a failure `code` and `reason`,
+   consistent with the other application-service result shapes.
+
+## 14. Contract identity and clauses
+
+1. Each clause is
+   `{ clauseId: buildClauseIdentity(primitive), category, expectedDependentMode?, primitive, supportingEvidence }`.
+   There is no `supersedesBaselineClauseIds`.
+2. `contractRequestId` is
+   `buildFrontendContractRequestIdentity(source.observationId, clauses.map(({ primitive }) => ({ primitive })), [])`.
+3. `contractId` is `buildFrontendContractInstanceIdentity(contractRequestId)`.
+   Unit-verified: the same request id with a fresh instance id.
+4. The contract is an ordinary `PerChangeContract` with canonical kind,
+   schema version `1.0.0`, and class `change`. It gets no annotation-specific
+   fields.
+
+## 15. Supporting evidence references
+
+Each clause carries exactly these two existing `EvidenceReference` values:
+
+1. `visualAnnotation.<annotationId>.source`
+2. `visualAnnotation.<annotationId>.items.<annotationItemId>`
+
+The annotation is never embedded (unit and browser verified).
+
+## 16. Configured baseline resolution
+
+1. The server promotion module reads the project config with
+   `readProjectConfig`.
+2. When `acceptance.contract` exists, it resolves `baselineArtifact` with
+   `resolveContainedAcceptancePath` and reads it with
+   `readPersistentBaselineContract`.
+   1. A missing, unsafe, unreadable, or invalid baseline gives 409 and no
+      contract.
+   2. Otherwise `activeBaselineIds` is `[baseline.baselineId]`.
+3. Without contract acceptance, `activeBaselineIds` is `[]`.
+4. Nothing is inferred from aliases, observations, annotations, existing
+   change contracts, or directory names.
+
+## 17. Project activation behavior
+
+1. `projectPaths.ts` adds `projectContractsRoot(projectRoot)` and
+   `contractOutputLocation()`, which returns
+   `.frontend-observer/evidence/contracts`.
+2. `projectWorkflowService.ts` adds
+   `activateProjectChangeContract(projectRoot, changeArtifactPath)`:
+   1. It reads the raw on-disk JSON and validates it.
+   2. It requires an existing `acceptance.contract`. Otherwise it returns
+      `not-configured` without writing.
+   3. It changes only `acceptance.contract.changeArtifact`, keeping key order
+      and every other value.
+   4. It validates the full updated configuration before writing and never
+      writes an invalid one.
+   5. It writes atomically with the existing `atomicTextWrite`.
+3. Activation happens only when `activateForCheck` is `true`. The result is
+   `not-requested`, `activated`, `not-configured` (with the exact bounded
+   reason), or `failed`. A failure never deletes the persisted contract and
+   never retries.
+4. Unit-verified: the updated config is re-read through the unchanged
+   `check` acceptance helpers (`resolveContainedAcceptancePath` and
+   `readPerChangeContract`), and the new contract loads. `projectCheckService.ts`
+   was not modified.
+
+## 18. Promotion API
+
+1. `POST /api/annotations/:handle/promote-contract`. `GET` and `HEAD` on it
+   return 405 `Allow: POST`.
+2. `POST /api/annotations/:handle/materialize-reference` still returns 405.
+   PUT, PATCH, and DELETE stay unsupported.
+3. The route uses one shared gate, `readAuthoringJsonRequest`, extracted from
+   the Prompt 2 save handler and now used by both routes. It covers authoring
+   enabled, Host, Origin, token, JSON content type, identity encoding, the
+   262144-byte limit, and JSON parsing. There is no second token, session, or
+   parser.
+4. The body is closed to `{ itemIds, activateForCheck }`:
+   1. `itemIds` is non-empty, at most 100, non-empty strings, unique.
+   2. `activateForCheck` is a required boolean.
+   3. Unknown fields give 400.
+5. The new module `src/viewerServer/annotationContractPromotion.ts` owns the
+   route use case. It was added so the route stays thin.
+   1. It resolves the annotation with `getAnnotationView`, which uses
+      `loadArtifactByHandle`.
+   2. It requires the runtime source. Reference annotations give 409.
+   3. It resolves the exact source through the Prompt 2 annotation source
+      view plus `loadArtifactByHandle`. A missing source gives 404.
+   4. It resolves the configured baseline, calls
+      `promoteVisualAnnotationContract` once with `contractOutputLocation()`
+      and the project root, and then optionally activates.
+   5. It runs through the session's single authoring write queue. That queue
+      is the Prompt 2 queue exposed as `runSerializedAuthoringWrite`, so
+      promotion never interleaves with saves.
+6. Status mapping:
+   1. 201: success.
+   2. 400: request shape or malformed handle.
+   3. 403: security gate.
+   4. 404: unknown annotation or missing source.
+   5. 409: not an annotation, a reference annotation, invalid project config,
+      invalid configured baseline, or source mismatch.
+   6. 413: body too large. 415: media type or encoding.
+   7. 422: non-promotable selection.
+   8. 500: persistence failure.
+7. The 201 body is exactly
+   `{ ok, contractId, contractRequestId, handle, clauseCount, activation }`.
+   The handle is `change-contract:contracts%2F<contractId>`. No paths are
+   returned.
+8. `VIEWER_PROTOCOL_VERSION` is now `1.2.0`. The Prompt 2 security test was
+   updated for the new version and for the now-real promote route. Its 405
+   list still includes `materialize-reference`.
+
+## 19. Runtime promotion UI
+
+1. `RuntimeAnnotationPanel` gains two sections. No runtime controls were
+   added to the reference panel.
+   1. "Runtime intent": operation, direction, category, mode, property,
+      tolerance, "Set candidate intent", the promotion status line, and
+      "Confirm runtime intent".
+   2. "Confirmed contract intent".
+2. Promotion is disabled with "Save the annotation before promoting contract
+   intent." while the draft is dirty or unsaved. The draft is never saved
+   silently.
+3. For a saved, clean annotation there is one checkbox per confirmed change
+   item, showing operation, category, and primitive summary.
+   1. Non-promotable confirmed items such as remove show a disabled checkbox
+      and a reason.
+   2. Inspect and candidate items are not listed.
+4. "Activate this change contract for project check" defaults to unchecked.
+5. "Promote selected to change contract" sends only the checked item ids, in
+   check order, through the new hook `useAnnotationContractPromotion` with the
+   in-memory token.
+6. Success shows the contract id, clause count, and activation state in
+   words. Local decision: a successful promotion clears the checkbox
+   selection so the same items are not promoted again by accident.
+7. Errors show a bounded message per status, keep the draft and
+   confirmations, and never retry.
+
+## 20. Existing evaluator authority
+
+1. Unit test: an annotation over real before/after observations (workspace
+   width 600 to 650) is promoted into a contract with
+   `resize wider (expected-dependent required)` and
+   `preserve height (absolute-px 2)`.
+2. The existing `evaluateFrontendContract` gives the same `overallVerdict`,
+   the same clause ids, and the same per-clause statuses (pass, pass) for
+   that contract and for an equivalent hand-authored `PerChangeContract`.
+3. A source search of all new and changed Batch 5 source found no PASS/FAIL
+   logic and no call to the evaluator. The only hit is a doc comment saying
+   the evaluator is the only authority.
+4. No annotation evaluator exists.
+
+## 21. Temporary-directory discovery hardening
+
+1. Implemented. `src/viewerServer/evidence/discovery.ts` never descends into a
+   directory whose basename starts with `.tmp-`, at any depth. The prefix is
+   the new exported `WRITER_TEMP_DIRECTORY_PREFIX`. Every canonical writer in
+   `src/artifacts/` uses it for its sibling temp directory.
+2. The skipped directory is not read, classified, returned, or deleted.
+3. Final artifact discovery is unchanged:
+   1. A normal directory is discovered.
+   2. The same artifact renamed from `.tmp-abc` to `final-abc` is discovered.
+   3. A name like `x.tmp-y` is still discovered.
+   4. All existing discovery tests pass.
+4. Structural test (`tests/unit/evidenceDiscoveryTempDirectories.test.ts`):
+   manifests under `.tmp-top`, `annotations/.tmp-abc`, `contracts/.tmp-def`,
+   and `references/nested/.tmp-ghi` are not discovered. This test failed
+   before the change and passes after it.
+5. Concurrency regression: 25 atomic annotation saves while
+   `buildEvidenceIndexMetadata` runs continuously. Before committing, a
+   heavier ad-hoc probe also ran against the unfixed code: 4 concurrent
+   refresh loops and 60 saves of 40 items each. The probe file was deleted.
+   Neither reproduced `EPERM` in-process, before or after the change.
+6. Conclusion: the Windows writer/discovery race is structurally mitigated.
+   Discovery can no longer hold handles inside a writer's temp directory. It
+   is not claimed as proven fixed, because no deterministic reproduction was
+   available.
+7. The concurrency test remains as a regression guard. The writers were not
+   changed and no retry loop was added.
+
+## 22. Unit tests
+
+1. `tests/unit/viewerRuntimeIntentModel.test.ts` (15 tests):
+   1. Vocabulary and `unexpected` refused.
+   2. All 4 move and all 4 resize mappings.
+   3. Arrow geometry never used.
+   4. Preserve property, tolerance bounds, pairwise and page-level
+      relationships.
+   5. Remove without a primitive, inspect.
+   6. Expected-dependent mode rule.
+   7. Unbound and incompatible combinations refused.
+   8. Built items accepted by the canonical annotation validator.
+   9. Retargeting, relationship rewrite, and clearing on incompatible
+      association.
+   10. Invalidation on move, intent change, and note edit; no-op keeps
+       confirmation.
+   11. Promotion status, including the exact remove message.
+2. `tests/unit/visualAnnotationContractPromotion.test.ts` (5 tests):
+   1. Canonical contract equality, including clause ids, request id, evidence
+      paths, selection order, and selected-only.
+   2. Persistence called once, fresh contract id, `activeBaselineIds`
+      preserved.
+   3. Expected-dependent mode, no `supersedesBaselineClauseIds`.
+   4. Reference source rejected, and four source-identity mismatches.
+   5. Ten invalid selections rejected atomically, and evaluator authority.
+3. `tests/unit/viewerAnnotationContractPromotion.test.ts` (9 tests):
+   1. Security gate reuse: token, Origin, Host, 415, 413, closed shape, 405,
+      and materialize still 405.
+   2. Read-only viewer 403.
+   3. Unknown, malformed, wrong family, and reference annotation.
+   4. Invalid configured baseline 409, source gone 404.
+   5. Unsupported, mixed, or unknown selection 422 with no contract.
+   6. Selected-only success with bounded response, no paths, loadable change
+      contract, config untouched.
+   7. `not-configured` activation.
+   8. Configured baseline id plus `activated` changing only `changeArtifact`,
+      with the check acceptance path readable.
+   9. `failed` activation (mocked writer failure) keeps the contract.
+4. `tests/unit/projectWorkflow.test.ts` (+4 tests): contract path helpers;
+   activation updates only `changeArtifact` with key order preserved; no
+   acceptance means no mutation; an invalid full config is never written.
+5. `tests/unit/evidenceDiscoveryTempDirectories.test.ts` (2 tests), see
+   section 21.
+6. `tests/unit/viewerAuthoringSecurity.test.ts` updated for protocol `1.2.0`
+   and the new real POST route.
+
+## 23. Browser tests
+
+New `tests/browser/runtimeAnnotationContractPromotion.test.ts` has 6
+real-Chromium tests. It reuses `writeInitializedProject` and `TestResources`.
+The file passed on repeated runs.
+
+1. Move to contract, and arrow non-inference:
+   1. An arrow pointing right is uninterpreted and blocked while unbound.
+   2. Associating `header` and choosing move left gives
+      `property-decreases header.x`.
+   3. A rectangle on `sidebar` with move right gives
+      `property-increases sidebar.x`.
+   4. Both are confirmed.
+   5. Promotion is disabled until saved.
+   6. Promotion yields exact clauses, evidence paths, and empty
+      `activeBaselineIds`.
+2. Selected only:
+   1. Expected-dependent resize wider requires a mode (permitted).
+   2. Preserve `sidebar.width` with absolute-px 2.
+   3. Preserve a canonical relationship.
+   4. Selecting 2 of 3 gives exactly 2 clauses in selection order. The third
+      item is promoted separately.
+3. Remove, inspect, and candidate:
+   1. Confirmed remove shows the exact unsupported message and a disabled
+      checkbox.
+   2. Inspect and candidate are not listed, and Promote is disabled.
+   3. Forced API promotion of each gives 422, and no contract exists.
+4. Confirmation invalidation: target change retargets to `footer` and goes
+   back to candidate; reconfirm; a mark move goes back to candidate;
+   reconfirm; promotion yields `property-increases footer.y`.
+5. Explicit activation: with a configured baseline, promotion with the
+   checkbox gives `activated`. The config equals the original except
+   `changeArtifact`, and `activeBaselineIds` is the configured baseline id.
+6. Not configured: activation requested gives `not-configured`, the contract
+   is persisted, and the config bytes are unchanged.
+
+## 24. Regression validation
+
+Every command below was run on Windows in the repository root.
+
+1. `npm run typecheck`: PASS
+2. `npm run lint`: PASS
+3. `npm test`: PASS (82 files, 1351 tests)
+4. `npm run build`: PASS
+5. `npm run test:browser`: PASS (24 files, 227 tests, real Chromium). This
+   includes `runtimeAnnotationAuthoring`, `referenceAnnotationAuthoring`,
+   `projectWorkflowViewer`, `pwaHardening`, `observationSvgWorkspace`, and
+   the existing contract evaluation and reference suites.
+6. `npm run test:security`: PASS (unit: 15 files, 158 tests. Browser: 3 files,
+   77 tests). This is after adding the two new security-relevant unit suites
+   to the script.
+7. `npm run check:docs`: PASS
+8. `npm pack --dry-run`: PASS (352 files, 919.1 kB)
+
+## 25. Security regression
+
+1. Both authoring POST routes share one gate. The Prompt 2 Host, Origin,
+   token, body, method, and PWA tests pass, and the promotion route's own
+   gate tests pass.
+2. The token stays in React memory only. The promotion request sends it only
+   in the authoring header.
+3. The promotion route returns no filesystem paths. It writes only a
+   canonical contract under `.frontend-observer/evidence/contracts` and, when
+   explicitly requested and configured, one field of the project config.
+4. `package.json` (additional file): the `test:security` script now also runs
+   `viewerAnnotationContractPromotion.test.ts` and
+   `evidenceDiscoveryTempDirectories.test.ts`. No version or dependency
+   changed.
+
+## 26. Scope audit
+
+1. ContractPrimitive vocabulary changed: false
+2. frontend-contract schema changed: false
+3. annotation schema changed: false
+4. reference materialization implemented: false
+5. external-reference schema changed: false
+6. reference approval changed: false
+7. project config schema changed: false
+8. alias catalog schema changed: false
+9. annotation evaluator added: false
+10. package version changed: false
+11. dependency changed: false
+
+No file under `src/domain/` or `src/artifacts/` changed.
+`frontendContractPersistenceService.ts`, `frontendContractEvaluationService.ts`,
+and `projectCheckService.ts` are unchanged. Prompt 4 reference authoring is
+unchanged (its 19 browser tests and 18 unit tests pass).
+
+## 27. Changed files
+
+### 27.1 Added production files
+
+1. `src/application/visualAnnotationContractPromotionService.ts`
+2. `src/viewerServer/annotationContractPromotion.ts` (route use case, keeps
+   the HTTP layer thin)
+3. `viewer/src/annotation/runtimeIntent.ts`
+4. `viewer/src/annotation/confirmation.ts` (shared confirmation rules moved
+   from `referenceIntent.ts`)
+5. `viewer/src/hooks/useAnnotationContractPromotion.ts` (promotion request
+   state)
+
+### 27.2 Modified production files
+
+1. `src/viewerServer/httpServer.ts`
+2. `src/viewerServer/annotationAuthoring.ts` (exposes the shared write queue)
+3. `src/viewerServer/evidence/discovery.ts`
+4. `src/projectWorkflow/projectPaths.ts`
+5. `src/application/projectWorkflowService.ts`
+6. `viewer/src/components/RuntimeAnnotationPanel.tsx`
+7. `viewer/src/components/ObservationWorkspace.tsx`
+8. `viewer/src/hooks/useRuntimeAnnotationDraft.ts`
+9. `viewer/src/annotation/referenceIntent.ts` (imports the shared confirmation
+   helpers, behavior unchanged)
+10. `viewer/src/types/contracts.ts` (type-only `ContractTolerance` re-export)
+11. `viewer/src/styles/index.css`
+12. `package.json` (`test:security` script only)
+
+### 27.3 Tests and report
+
+1. Added: `tests/browser/runtimeAnnotationContractPromotion.test.ts`
+2. Added: `tests/unit/visualAnnotationContractPromotion.test.ts`
+3. Added: `tests/unit/viewerAnnotationContractPromotion.test.ts`
+4. Added: `tests/unit/viewerRuntimeIntentModel.test.ts`
+5. Added: `tests/unit/evidenceDiscoveryTempDirectories.test.ts`
+6. Modified: `tests/unit/projectWorkflow.test.ts`
+7. Modified: `tests/unit/viewerAuthoringSecurity.test.ts`
+8. Added: `docs/reports/v0.9-batch5-runtime-intent-contract-promotion.md`
+
+### 27.4 Generated paths
+
+1. `dist/` was rebuilt. It is ignored.
+2. Tests create and remove temporary directories under the OS temp directory.
+3. Validation logs went to the session scratchpad.
+
+## 28. Remaining next step
+
+v0.9 Prompt 6 — Canonical external-reference region/requirement materialization