@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-batch1-visual-annotation-foundation.md

@@ -0,0 +1,351 @@
+# v0.9 Batch 1 Report: Visual Annotation Foundation
+
+## 1. VERDICT
+
+PASS_V0_9_BATCH1_VISUAL_ANNOTATION_FOUNDATION
+
+## 2. Repository identity
+
+1. Repository: `C:\Users\daile\Projects\my-frontend-observer`
+2. Branch: `master`
+3. Local HEAD at session start: `473713d240af09e752eeb8e00735738c4927b16d`
+4. Starting HEAD for implementation: `59cfb6fd29a0c3c394d6115213edf92c1106104f`
+   (the expected v0.9 planning commit on `origin/master`)
+5. Ending HEAD before the final commit: `59cfb6fd29a0c3c394d6115213edf92c1106104f`
+6. Package version: `0.8.1` (unchanged in `package.json` and `package-lock.json`)
+
+### 2.1 Preflight handling
+
+The first preflight found local `master` three commits behind `origin/master`.
+It also found one untracked local file,
+`docs/reports/v0.9-architecture-retrieval.md`. That path is tracked on
+`origin/master` with different content. The first run stopped with
+`BLOCKED_V0_9_BATCH1_DIRTY_WORKTREE`.
+
+The user then told the agent to keep the local copy, not delete it, and
+continue. The agent did the following:
+
+1. Copied the local file to
+   `.my-dev-kit-workflow/adhoc/preserved-local-docs/v0.9-architecture-retrieval.md`.
+   It checked that the SHA-256 of the copy matched the original. This folder is
+   ignored by Git.
+2. Moved the original to
+   `.my-dev-kit-workflow/adhoc/preserved-local-docs/v0.9-architecture-retrieval.md.moved`.
+3. Ran `git merge --ff-only origin/master`. This fast-forwarded `master` to `59cfb6f`.
+4. Copied the local content back to `docs/reports/v0.9-architecture-retrieval.md`.
+5. Ran `git update-index --skip-worktree docs/reports/v0.9-architecture-retrieval.md`.
+   Git now leaves the local copy alone and the worktree reports clean.
+
+This commit does not include that file. To go back to the tracked version, run
+`git update-index --no-skip-worktree docs/reports/v0.9-architecture-retrieval.md`.
+
+## 3. Frozen scope implemented
+
+1. `src/domain/visualAnnotation.ts` holds the frozen constants and all
+   annotation types: source, mark, association, intent, interpretation, item,
+   and artifact. It also holds the one canonical structural validator,
+   `isValidVisualAnnotationArtifact`, and the pure deterministic overlay
+   renderer, `renderVisualAnnotationOverlaySvg`.
+2. `src/domain/visualAnnotationIdentity.ts` holds
+   `buildVisualAnnotationRequestIdentity`, a deterministic semantic SHA-256
+   identity. It also holds `buildVisualAnnotationInstanceIdentity`, a fresh
+   `randomBytes(16)` instance identity.
+3. `src/artifacts/visualAnnotationArtifactWriter.ts` is an immutable, atomic,
+   manifest-last writer. It re-derives the overlay and verifies its digest
+   before writing.
+4. `src/artifacts/visualAnnotationArtifactReader.ts` is the canonical reader.
+   It validates the manifest and checks that the owned overlay is a regular
+   file whose SHA-256 matches the manifest.
+5. `src/application/visualAnnotationPersistenceService.ts` holds
+   `persistVisualAnnotation`, the one Batch 1 save use case.
+6. `src/index.ts` adds the public Batch 1 exports.
+
+## 4. Domain contract
+
+1. Artifact kind: `my-frontend-observer/visual-annotation`
+2. Schema version: `1.0.0`
+3. Source contexts (2): `runtime-observation` and `external-reference`
+4. Coordinate kinds: `runtime-css-px` for runtime sources and
+   `reference-image-px` for reference sources. A cross-domain coordinate kind
+   is rejected.
+5. Mark kinds (5): `point`, `rectangle`, `line`, `arrow`, `note`
+6. Intent kinds: `inspect`, `change`, `reference-region`,
+   `reference-requirement`, `asset-sensitive`. Runtime sources accept
+   `inspect` and `change`. Reference sources accept `inspect`,
+   `reference-region`, `reference-requirement`, and `asset-sensitive`.
+7. Interpretation states: `uninterpreted`, `candidate`, `confirmed`
+8. Item bound: `MAX_VISUAL_ANNOTATION_ITEMS = 100`
+9. Note bound: `MAX_VISUAL_ANNOTATION_NOTE_LENGTH = 2000`
+
+### 4.1 Canonical validators reused
+
+1. Change categories use `isAuthoredChangeScopeCategory`. `unexpected` is not
+   a member, so it cannot be authored.
+2. Expected-dependent mode uses `isValidExpectedDependentMode`. The mode is
+   required when the category is `expected-dependent` and must be absent
+   otherwise. This is the same rule `PerChangeClause` and
+   `RawReferenceRequirement` apply. Neither owning module exports the combined
+   check as a function, so Batch 1 applies the rule using the two exported
+   validators.
+3. Contract primitives use `isValidContractPrimitive`.
+4. Reference-region intent uses `isValidReferenceRegions([region], width, height)`.
+   This covers the region id pattern, rectangle validity, and the source image
+   bounds.
+5. Reference-requirement intent uses `isValidRawReferenceRequirement`.
+6. Relationship kinds come from `PAIRWISE_RELATIONSHIP_KINDS` and
+   `PAGE_LEVEL_RELATIONSHIP_KINDS`.
+
+### 4.2 Local implementation choices
+
+These choices were left open by the frozen plan and this prompt.
+
+1. Every annotation object is a closed shape. Unknown fields are rejected, the
+   same way `isValidContractPrimitive` already rejects them. This is how the
+   validator rejects mixed forms, such as a candidate with `confirmedAt`, and
+   stray fields such as an alias or a viewer URL.
+2. A runtime `runtime-relationship` with a pairwise kind needs two non-empty,
+   distinct targets. This matches `PairwiseLayoutRelationship`. A page-level
+   kind must not carry targets. This matches `PageLevelLayoutRelationship`.
+3. A reference source with lifecycle `imported` must have
+   `imageOwnerReferenceId` equal to `referenceId`. A reference source with
+   lifecycle `approved` must name a different owning reference. This mirrors
+   the existing external-reference ownership model.
+4. `annotationId` names the artifact directory. The validator requires it to
+   be a single safe path segment: no separators, no colon, no NUL, and not
+   `.` or `..`. `source.screenshot.path` follows the same bare-filename rule.
+5. Invalid content given to the persistence service is refused with the
+   existing `invalid-request` diagnostic. No new diagnostic code was added.
+6. Batch 1 does not check whether an associated target or region exists in
+   another artifact. It does not check `contractPrimitive` against the item's
+   association either. Those checks belong to later batches.
+
+## 5. Identity contract
+
+1. The request identity hashes exactly
+   `{ source, items, supersedes: supersedesAnnotationId ?? null }`. The hash is
+   built by sorting object keys recursively, keeping array order, serializing
+   to JSON, and taking the lowercase SHA-256 hex. The module has its own
+   private `canonicalize`, which follows the repository convention.
+2. Excluded from the request identity: `createdAt`, the output location, cwd,
+   project root, alias, viewer port, HTTP handle, temporary directory, overlay
+   SHA, and `annotationId`. The function accepts none of these as inputs.
+3. Instance identity is `${annotationRequestId}-${randomBytes(16).toString('hex')}`.
+   It is never based on a timestamp.
+4. Supersession is carried forward as given. It is part of the request
+   identity, and the validator rejects an empty value or a value equal to
+   `annotationId`. Batch 1 does not resolve lineage.
+
+## 6. Overlay contract
+
+1. Owned filename: `annotation-overlay.svg`. The manifest `overlay.path` must
+   be exactly this value, and `overlay.format` must be `svg`.
+2. The root element uses the source dimensions:
+   `<svg xmlns="http://www.w3.org/2000/svg" width="W" height="H" viewBox="0 0 W H">`.
+   The manifest `overlay.width` and `overlay.height` must equal the source
+   coordinate-space dimensions.
+3. Determinism:
+   1. Output depends only on the source dimensions and the marks, rendered in
+      the persisted item order.
+   2. Style values are fixed constants.
+   3. Numbers are formatted with `String(n)`, and `-0` is written as `0`.
+   4. Lines end with `\n`.
+   5. The arrowhead is built with `Math.sqrt` vector math, not trigonometry.
+   6. Output never depends on interpretation state, item ids, timestamps,
+      random values, environment, locale, or the filesystem.
+4. Mark mapping:
+   1. A point becomes a circle.
+   2. A rectangle becomes a rect.
+   3. A line becomes a line.
+   4. An arrow becomes a line plus a filled polygon arrowhead. A zero-length
+      arrow gets no arrowhead.
+   5. A note becomes a filled anchor circle plus a text element.
+5. The SVG has no image, script, foreignObject, href, marker ids, CSS imports,
+   or event handlers. It never embeds the source image.
+6. SHA-256 verification:
+   1. The service hashes the rendered UTF-8 bytes.
+   2. The writer re-renders the overlay and refuses to write if the digest
+      differs from `overlay.sha256`.
+   3. The reader hashes the bytes on disk and refuses them if the digest does
+      not match.
+7. Text escaping: note text escapes `&`, `<`, `>`, `"`, and `'`. Characters
+   that XML 1.0 does not allow are replaced with U+FFFD in the overlay only.
+   The manifest keeps the authored text exactly as written.
+
+## 7. Persistence contract
+
+1. Final directory: `<outputLocation>/<annotationId>/`
+2. Temporary directory: `<outputLocation>/.tmp-<annotationId>`
+3. Write order:
+   1. Validate the artifact.
+   2. Render the overlay and verify its digest.
+   3. Refuse if the final directory already exists.
+   4. Remove this artifact's own stale temporary directory, if one exists.
+   5. Create the temporary directory.
+   6. Write `annotation-overlay.svg`.
+   7. Write `manifest.json`.
+4. Atomic rename: the temporary directory is renamed to the final directory in
+   one `rename` call.
+5. No overwrite: if the final directory already exists, the writer returns
+   `artifact-write-failure` and leaves the existing files untouched.
+6. Failure cleanup: on any failure after the temporary directory is created,
+   the writer removes it and returns `artifact-write-failure`.
+7. The writer never reads or copies source observation or reference bytes.
+8. The service checks the output location with `normalizeOutputLocation`. It
+   uses `getProducerInfo()` and sets `provenance.origin` to `viewer`. It
+   writes exactly once.
+
+## 8. Tests added
+
+1. `tests/unit/visualAnnotationFixtures.ts` is a shared fixture helper, not a
+   test file.
+2. `tests/unit/visualAnnotation.test.ts` covers:
+   1. The frozen constants.
+   2. A: a valid runtime artifact.
+   3. B: a valid reference artifact, both imported and approved.
+   4. An empty item list, and all five mark kinds.
+   5. C: cross-domain associations, and association shapes checked against
+      the relationship vocabularies.
+   6. D: cross-domain intents, and every intent valid in its own context.
+   7. Delegation to the canonical validators for primitives, regions,
+      requirements, category, and mode.
+   8. E: bounds for all out-of-frame and non-finite marks, freehand and
+      polygon rejection, and an edge-touching rectangle.
+   9. F: notes of 2000 characters (valid), 2001 characters (invalid), and
+      empty (invalid).
+   10. G: 100 items (valid) and 101 items (invalid).
+   11. H: duplicate and empty item ids.
+   12. I: interpretation states and malformed mixtures.
+   13. J: authored `unexpected` is rejected.
+   14. K: remove with a primitive is rejected, remove without one is accepted.
+   15. Malformed sources and artifact envelopes.
+   16. Overlay tests: root frame and item order, determinism, independence
+       from interpretation, no forbidden content, escaping of malicious text,
+       and a zero-length arrow.
+3. `tests/unit/visualAnnotationIdentity.test.ts` covers:
+   1. The hex format of the request identity.
+   2. The same content gives the same identity.
+   3. Key insertion order does not change the identity.
+   4. Item order does change it.
+   5. Changes to the source, coordinates, association, interpretation, or
+      supersession change it.
+   6. Timestamp and output location are excluded.
+   7. Instance identity is fresh on every call.
+4. `tests/unit/visualAnnotationArtifactWriter.test.ts` covers:
+   1. A successful write, with the exact directory name, `manifest.json`, and
+      `annotation-overlay.svg`.
+   2. Reader round trips for runtime and reference artifacts.
+   3. Refusal to overwrite an existing directory.
+   4. No source bytes copied into the annotation directory.
+   5. No temporary directory after success, including a stale one.
+   6. No temporary directory after a filesystem failure.
+   7. Refusal on an overlay SHA mismatch.
+5. `tests/unit/visualAnnotationArtifactWriterFailure.test.ts` covers the
+   section 19 failure cases:
+   1. Case 1: an invalid artifact is refused.
+   2. Case 2: an existing final directory is left unchanged.
+   3. Case 3: the manifest write fails after the overlay write. The test
+      checks write order, that no artifact appears, and that temp is cleaned.
+   4. Case 4: the atomic rename fails.
+   5. Case 5: malformed JSON, plus a missing manifest.
+   6. Case 6: a structurally invalid artifact and an unsupported schema version.
+   7. Case 7: a missing overlay, plus an overlay path that is a directory.
+   8. Case 8: an overlay SHA mismatch.
+   9. Case 9: malicious note text is persisted as escaped SVG, and the
+      manifest text is preserved.
+6. `tests/unit/visualAnnotationPersistence.test.ts` covers:
+   1. Runtime persistence: identity, producer, provenance, overlay metadata,
+      overlay SHA, and a reader round trip.
+   2. External-reference persistence.
+   3. Saving the same content twice gives the same request identity and a
+      fresh `annotationId`.
+   4. `supersedesAnnotationId` is carried forward, and the prior artifact's
+      bytes are unchanged.
+   5. Invalid content, an empty supersedes value, and unsafe output locations
+      are refused, and nothing is written.
+
+The focused run passed: 5 test files and 59 tests.
+
+## 9. Validation
+
+Every command below was actually run on Windows in the repository root.
+
+1. `npm run typecheck`: PASS (exit 0)
+2. `npm run lint`: PASS (exit 0)
+3. `npm test`: PASS (73 test files and 1239 tests passed)
+4. `npm run build`: PASS (exit 0, TypeScript build plus viewer Vite/PWA build)
+5. `npm run check:docs`: PASS ("Documentation check passed (17 required files).")
+6. `npm pack --dry-run`: PASS (333 files, 856.2 kB package size). The five new
+   `dist` modules are included. No agent-control files are included.
+
+Additional check: after the build, `node` imported `dist/index.js`. It
+resolved all the new public functions and constants with the frozen values.
+
+Skipped: browser tests (`npm run test:browser`) and packed clean-consumer
+proof. Batch 1 changes no browser, viewer, CLI, or package-entry behavior, and
+this prompt does not require them.
+
+## 10. Scope audit
+
+1. viewer source changed: false
+2. viewer server changed: false
+3. CLI changed: false
+4. project workflow changed: false
+5. contract primitives changed: false
+6. external-reference schema changed: false
+7. package version changed: false
+
+No dependency was added or changed. No POST route, UI, CLI command, contract
+promotion, reference materialization, or project authoring support was added.
+
+## 11. Changed files
+
+1. `src/domain/visualAnnotation.ts` (added)
+2. `src/domain/visualAnnotationIdentity.ts` (added)
+3. `src/artifacts/visualAnnotationArtifactWriter.ts` (added)
+4. `src/artifacts/visualAnnotationArtifactReader.ts` (added)
+5. `src/application/visualAnnotationPersistenceService.ts` (added)
+6. `src/index.ts` (modified, exports only)
+7. `tests/unit/visualAnnotationFixtures.ts` (added)
+8. `tests/unit/visualAnnotation.test.ts` (added)
+9. `tests/unit/visualAnnotationIdentity.test.ts` (added)
+10. `tests/unit/visualAnnotationArtifactWriter.test.ts` (added)
+11. `tests/unit/visualAnnotationArtifactWriterFailure.test.ts` (added)
+12. `tests/unit/visualAnnotationPersistence.test.ts` (added)
+13. `docs/reports/v0.9-batch1-visual-annotation-foundation.md` (added)
+
+### 11.1 Additional public exports
+
+These go beyond the minimum export list:
+
+1. `VISUAL_ANNOTATION_OVERLAY_PATH`
+2. `isValidVisualAnnotationContent`, the content half of the artifact
+   validator. The service uses it before deriving identity.
+3. `VISUAL_ANNOTATION_MANIFEST_FILENAME` and `VISUAL_ANNOTATION_OVERLAY_FILENAME`
+4. `computeVisualAnnotationOverlaySha256`, shared by the writer, reader, and
+   service.
+5. Result and options types: `PersistedVisualAnnotationResult`,
+   `WriteVisualAnnotationArtifactOptions`, `ReadVisualAnnotationArtifactResult`,
+   `PersistVisualAnnotationOptions`, `ApplicationPersistVisualAnnotationResult`.
+
+### 11.2 Generated paths
+
+1. `dist/` was rebuilt by `npm run build`. It is ignored by Git.
+2. `.my-dev-kit-workflow/adhoc/preserved-local-docs/` holds the preserved
+   local retrieval report. It is ignored by Git.
+3. Unit tests create temporary directories with `mkdtemp` under the OS temp
+   directory, following the existing test convention. Each test removes its
+   own directories.
+4. Validation logs were written to the session scratchpad, outside the
+   repository.
+
+### 11.3 Remaining risks
+
+1. The local retrieval report is hidden from Git by `skip-worktree`. A later
+   pull that changes the tracked version of that file will stop until the
+   flag is cleared.
+2. Resolving targets and regions across artifacts, and checking revision
+   lineage, are deferred to later batches by design.
+
+## 12. Remaining next step
+
+v0.9 Prompt 2 — Viewer discovery, project authoring boundary, and secure POST API