@dailephd/my-frontend-observer 0.8.1 → 0.9.1

package/dist/application/visualAnnotationPersistenceService.js

@@ -0,0 +1,68 @@
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+import { getProducerInfo } from '../domain/schema.js';
+import { VISUAL_ANNOTATION_ARTIFACT_KIND, VISUAL_ANNOTATION_SCHEMA_VERSION, VISUAL_ANNOTATION_OVERLAY_PATH, isValidVisualAnnotationContent, renderVisualAnnotationOverlaySvg, } from '../domain/visualAnnotation.js';
+import { buildVisualAnnotationRequestIdentity, buildVisualAnnotationInstanceIdentity } from '../domain/visualAnnotationIdentity.js';
+import { normalizeOutputLocation } from '../request/paths.js';
+import { writeVisualAnnotationArtifact, computeVisualAnnotationOverlaySha256 } from '../artifacts/visualAnnotationArtifactWriter.js';
+function failure(code, message) {
+    return { ok: false, diagnostics: [{ code, severity: DIAGNOSTIC_SEVERITY[code], message }] };
+}
+/**
+ * The one canonical Batch 1 application use case for saving a visual
+ * annotation: validates source/items through the canonical annotation domain,
+ * normalizes the portable output location, derives the deterministic request
+ * identity and a fresh instance identity, renders the deterministic overlay
+ * and its SHA-256, and persists exactly once through the canonical writer.
+ *
+ * It never reads a viewer alias, resolves another artifact, checks revision
+ * lineage, checks whether an associated target/region exists, promotes a
+ * contract, materializes a reference, or modifies project configuration.
+ */
+export async function persistVisualAnnotation(options) {
+    const contentValidation = isValidVisualAnnotationContent(options.source, options.items);
+    if (!contentValidation.valid)
+        return failure('invalid-request', `invalid visual annotation: ${contentValidation.reason}`);
+    if (options.supersedesAnnotationId !== undefined && options.supersedesAnnotationId.length === 0) {
+        return failure('invalid-request', 'supersedesAnnotationId must be a non-empty string when supplied');
+    }
+    const normalizedOutput = normalizeOutputLocation(options.outputLocation);
+    if (!normalizedOutput.ok)
+        return { ok: false, diagnostics: [normalizedOutput.diagnostic] };
+    const { source, items } = options;
+    const annotationRequestId = buildVisualAnnotationRequestIdentity(source, items, options.supersedesAnnotationId);
+    const annotationId = buildVisualAnnotationInstanceIdentity(annotationRequestId);
+    const overlaySha256 = computeVisualAnnotationOverlaySha256(renderVisualAnnotationOverlaySvg(source, items));
+    const artifact = {
+        artifactKind: VISUAL_ANNOTATION_ARTIFACT_KIND,
+        schemaVersion: VISUAL_ANNOTATION_SCHEMA_VERSION,
+        annotationRequestId,
+        annotationId,
+        ...(options.supersedesAnnotationId === undefined ? {} : { supersedesAnnotationId: options.supersedesAnnotationId }),
+        producer: getProducerInfo(),
+        source,
+        items,
+        overlay: {
+            path: VISUAL_ANNOTATION_OVERLAY_PATH,
+            format: 'svg',
+            width: source.coordinateSpace.width,
+            height: source.coordinateSpace.height,
+            sha256: overlaySha256,
+        },
+        provenance: {
+            createdAt: new Date().toISOString(),
+            origin: 'viewer',
+        },
+    };
+    const persisted = await writeVisualAnnotationArtifact(artifact, normalizedOutput.value, options.cwd === undefined ? {} : { cwd: options.cwd });
+    if (!persisted.ok)
+        return { ok: false, diagnostics: persisted.diagnostics };
+    return {
+        ok: true,
+        annotationId,
+        annotationRequestId,
+        artifactRoot: persisted.artifactRoot,
+        manifestPath: persisted.manifestPath,
+        overlayPath: persisted.overlayPath,
+    };
+}
+//# sourceMappingURL=visualAnnotationPersistenceService.js.map

package/dist/application/visualAnnotationPersistenceService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualAnnotationPersistenceService.js","sourceRoot":"","sources":["../../src/application/visualAnnotationPersistenceService.ts"],"names":[],"mappings":"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"}

package/dist/application/visualAnnotationReferenceMaterializationService.d.ts

@@ -0,0 +1,53 @@
+import type { VisualAnnotationArtifact, VisualAnnotationItem } from '../domain/visualAnnotation.js';
+import type { ExternalReferenceArtifact } from '../domain/externalReference.js';
+export interface MaterializeVisualAnnotationReferenceOptions {
+    annotation: VisualAnnotationArtifact;
+    sourceReference: ExternalReferenceArtifact;
+    /** Root directory of the selected source reference artifact, used only for canonical explicit supersession. */
+    sourceReferenceRoot: string;
+    /** The canonical source image bytes (verified here against the source image SHA-256). */
+    imageBytes: Uint8Array;
+    selectedItemIds: readonly string[];
+    outputLocation: string;
+    cwd?: string;
+}
+export type MaterializeVisualAnnotationReferenceFailureCode = 'invalid-source' | 'source-mismatch' | 'invalid-selection' | 'invalid-materialized-reference' | 'persistence-failure';
+export type MaterializeVisualAnnotationReferenceResult = {
+    ok: true;
+    referenceId: string;
+    referenceRequestId: string;
+    artifactRoot: string;
+    manifestPath: string;
+    imagePath: string;
+    lifecycle: 'imported';
+    supersedesReferenceId: string;
+    regionCount: number;
+    requirementCount: number;
+} | {
+    ok: false;
+    code: MaterializeVisualAnnotationReferenceFailureCode;
+    reason: string;
+};
+/** Maximum number of selected items accepted in one materialization (the annotation itself is bounded to 100 items). */
+export declare const MAX_MATERIALIZATION_ITEM_IDS = 100;
+/** Why one selected item cannot be materialized into a reference revision, or undefined when it can. */
+export declare function referenceMaterializationBlockReason(item: VisualAnnotationItem): string | undefined;
+/**
+ * v0.9 Batch 6: the one canonical annotation-to-reference materialization use
+ * case. Explicitly selected, confirmed `reference-region` (create/refine) and
+ * `reference-requirement` items of one saved external-reference annotation are
+ * composed onto the selected source reference's own regions, requirements,
+ * applicability, and label, and persisted exactly once through the canonical
+ * `importExternalReference` as a new imported revision that explicitly
+ * supersedes the source. The source reference is never modified, never
+ * approved, and its image bytes are reused verbatim.
+ *
+ * Composition order: source regions keep their order (a refined region keeps
+ * its position and id, with the confirmed rectangle); created regions are
+ * appended in selection order; then source requirements (content only) are
+ * followed by selected requirements in selection order. Every selected
+ * relationship requirement must still hold for the final region geometry,
+ * checked through the canonical requirement expectation derivation. Any
+ * invalid selected item rejects the whole materialization before any write.
+ */
+export declare function materializeVisualAnnotationReference(options: MaterializeVisualAnnotationReferenceOptions): Promise<MaterializeVisualAnnotationReferenceResult>;

package/dist/application/visualAnnotationReferenceMaterializationService.js

@@ -0,0 +1,194 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { isValidVisualAnnotationArtifact } from '../domain/visualAnnotation.js';
+import { isApprovedExternalReferenceArtifact, isValidExternalReferenceArtifact } from '../domain/externalReference.js';
+import { isValidReferenceRegions } from '../domain/externalReferenceRegions.js';
+import { buildReferenceRequirement, deriveReferenceRequirementExpectation, isValidRawReferenceRequirement, isValidReferenceRequirements } from '../domain/externalReferenceRequirements.js';
+import { importExternalReference } from './externalReferencePersistenceService.js';
+import { readExternalReferenceArtifact } from '../artifacts/externalReferenceArtifactReader.js';
+import { EXTERNAL_REFERENCE_MANIFEST_FILENAME } from '../artifacts/externalReferenceArtifactWriter.js';
+/** Maximum number of selected items accepted in one materialization (the annotation itself is bounded to 100 items). */
+export const MAX_MATERIALIZATION_ITEM_IDS = 100;
+function fail(code, reason) {
+    return { ok: false, code, reason };
+}
+/** Why one selected item cannot be materialized into a reference revision, or undefined when it can. */
+export function referenceMaterializationBlockReason(item) {
+    const { interpretation } = item;
+    if (interpretation.state === 'uninterpreted')
+        return 'the item has no interpretation';
+    if (interpretation.state === 'candidate')
+        return 'the item interpretation is a candidate, not confirmed';
+    const kind = interpretation.intent.kind;
+    if (kind === 'inspect' || kind === 'asset-sensitive')
+        return 'informational annotation intent is not materialized into the external-reference contract';
+    if (kind !== 'reference-region' && kind !== 'reference-requirement')
+        return `"${kind}" intent is not external-reference intent`;
+    return undefined;
+}
+/** The persisted requirement's authored content only - `requirementId` is never carried over; the canonical import recomputes it. */
+function toRawReferenceRequirement(requirement) {
+    return {
+        category: requirement.category,
+        ...(requirement.expectedDependentMode === undefined ? {} : { expectedDependentMode: requirement.expectedDependentMode }),
+        subject: requirement.subject,
+        ...(requirement.tolerance === undefined ? {} : { tolerance: requirement.tolerance }),
+    };
+}
+function sourceImageOf(reference) {
+    return isApprovedExternalReferenceArtifact(reference) ? reference.sourceReference.image : reference.image;
+}
+function sourceMatches(annotation, reference) {
+    const source = annotation.source;
+    if (source.kind !== 'external-reference')
+        return false;
+    const approved = isApprovedExternalReferenceArtifact(reference);
+    const image = sourceImageOf(reference);
+    const imageOwnerReferenceId = approved ? reference.sourceReference.referenceId : reference.referenceId;
+    return (source.referenceId === reference.referenceId &&
+        source.referenceRequestId === reference.referenceRequestId &&
+        source.referenceSchemaVersion === reference.schemaVersion &&
+        source.lifecycle === reference.lifecycle.state &&
+        source.imageOwnerReferenceId === imageOwnerReferenceId &&
+        source.imageSha256 === image.sha256 &&
+        source.coordinateSpace.width === image.width &&
+        source.coordinateSpace.height === image.height);
+}
+/**
+ * v0.9 Batch 6: the one canonical annotation-to-reference materialization use
+ * case. Explicitly selected, confirmed `reference-region` (create/refine) and
+ * `reference-requirement` items of one saved external-reference annotation are
+ * composed onto the selected source reference's own regions, requirements,
+ * applicability, and label, and persisted exactly once through the canonical
+ * `importExternalReference` as a new imported revision that explicitly
+ * supersedes the source. The source reference is never modified, never
+ * approved, and its image bytes are reused verbatim.
+ *
+ * Composition order: source regions keep their order (a refined region keeps
+ * its position and id, with the confirmed rectangle); created regions are
+ * appended in selection order; then source requirements (content only) are
+ * followed by selected requirements in selection order. Every selected
+ * relationship requirement must still hold for the final region geometry,
+ * checked through the canonical requirement expectation derivation. Any
+ * invalid selected item rejects the whole materialization before any write.
+ */
+export async function materializeVisualAnnotationReference(options) {
+    const { annotation, sourceReference, selectedItemIds } = options;
+    const annotationValidation = isValidVisualAnnotationArtifact(annotation);
+    if (!annotationValidation.valid)
+        return fail('invalid-source', `visual annotation is invalid: ${annotationValidation.reason}`);
+    if (annotation.source.kind !== 'external-reference')
+        return fail('invalid-source', 'only external-reference annotations can be materialized into a reference revision');
+    const referenceValidation = isValidExternalReferenceArtifact(sourceReference);
+    if (!referenceValidation.valid)
+        return fail('invalid-source', `source external reference is invalid: ${referenceValidation.reason}`);
+    if (!sourceMatches(annotation, sourceReference))
+        return fail('source-mismatch', 'the supplied reference is not the exact canonical source of this annotation');
+    // Supersession is resolved by the canonical import service from this root, so it must hold exactly the supplied source.
+    const rootRead = await readExternalReferenceArtifact(path.join(options.sourceReferenceRoot, EXTERNAL_REFERENCE_MANIFEST_FILENAME));
+    if (!rootRead.ok || rootRead.artifact.referenceId !== sourceReference.referenceId) {
+        return fail('source-mismatch', 'the source reference root does not contain the supplied source reference');
+    }
+    const image = sourceImageOf(sourceReference);
+    if (createHash('sha256').update(options.imageBytes).digest('hex') !== image.sha256) {
+        return fail('source-mismatch', 'the supplied image bytes do not match the source reference image SHA-256');
+    }
+    if (selectedItemIds.length === 0)
+        return fail('invalid-selection', 'select at least one confirmed reference intent item to materialize');
+    if (selectedItemIds.length > MAX_MATERIALIZATION_ITEM_IDS)
+        return fail('invalid-selection', `at most ${MAX_MATERIALIZATION_ITEM_IDS} items can be materialized at once`);
+    if (new Set(selectedItemIds).size !== selectedItemIds.length)
+        return fail('invalid-selection', 'selected annotation item ids must be unique');
+    const itemsById = new Map(annotation.items.map((item) => [item.annotationItemId, item]));
+    const selected = [];
+    for (const itemId of selectedItemIds) {
+        const item = itemsById.get(itemId);
+        if (item === undefined)
+            return fail('invalid-selection', `selected annotation item "${itemId}" does not exist in this annotation`);
+        const blocked = referenceMaterializationBlockReason(item);
+        if (blocked !== undefined)
+            return fail('invalid-selection', `annotation item "${itemId}" cannot be materialized: ${blocked}`);
+        selected.push({ itemId, intent: item.interpretation.intent });
+    }
+    // --- regions: refinements in place, then creates appended in selection order ---
+    const sourceRegions = sourceReference.regions ?? [];
+    const finalRegions = sourceRegions.map((region) => ({ id: region.id, rectangle: { ...region.rectangle } }));
+    const refinedIndexes = new Set();
+    const createdIds = new Set();
+    for (const { itemId, intent } of selected) {
+        if (intent.kind !== 'reference-region')
+            continue;
+        const lowerId = intent.region.id.toLowerCase();
+        if (intent.mode === 'refine') {
+            const index = sourceRegions.findIndex((region) => region.id.toLowerCase() === lowerId);
+            if (index < 0)
+                return fail('invalid-selection', `annotation item "${itemId}" refines region "${intent.region.id}", which does not exist in the source reference`);
+            if (refinedIndexes.has(index))
+                return fail('invalid-selection', `more than one selected item refines region "${intent.region.id}"`);
+            refinedIndexes.add(index);
+            finalRegions[index] = { id: sourceRegions[index].id, rectangle: { ...intent.region.rectangle } };
+        }
+    }
+    for (const { itemId, intent } of selected) {
+        if (intent.kind !== 'reference-region' || intent.mode !== 'create')
+            continue;
+        const lowerId = intent.region.id.toLowerCase();
+        if (sourceRegions.some((region) => region.id.toLowerCase() === lowerId))
+            return fail('invalid-selection', `annotation item "${itemId}" creates region "${intent.region.id}", which already exists in the source reference`);
+        if (createdIds.has(lowerId))
+            return fail('invalid-selection', `more than one selected item creates region "${intent.region.id}"`);
+        createdIds.add(lowerId);
+        finalRegions.push({ id: intent.region.id, rectangle: { ...intent.region.rectangle } });
+    }
+    const regionsValidation = isValidReferenceRegions(finalRegions, image.width, image.height);
+    if (!regionsValidation.valid)
+        return fail('invalid-materialized-reference', `resulting regions are invalid: ${regionsValidation.reason}`);
+    // --- requirements: source content first, then selected requirements in selection order ---
+    const rawRequirements = (sourceReference.requirements ?? []).map(toRawReferenceRequirement);
+    for (const { itemId, intent } of selected) {
+        if (intent.kind !== 'reference-requirement')
+            continue;
+        const rawValidation = isValidRawReferenceRequirement(intent.requirement);
+        if (!rawValidation.valid)
+            return fail('invalid-selection', `annotation item "${itemId}" has an invalid requirement: ${rawValidation.reason}`);
+        if (intent.requirement.subject.kind === 'region-relationship') {
+            const expectation = deriveReferenceRequirementExpectation(intent.requirement.subject, finalRegions);
+            if (!expectation.available || expectation.kind !== 'relationship' || !expectation.matches) {
+                return fail('invalid-materialized-reference', `annotation item "${itemId}" requires a region relationship that the resulting region geometry does not exhibit`);
+            }
+        }
+        rawRequirements.push(intent.requirement);
+    }
+    const builtRequirements = rawRequirements.map((raw) => buildReferenceRequirement(raw));
+    const requirementsValidation = isValidReferenceRequirements(builtRequirements, finalRegions);
+    if (!requirementsValidation.valid)
+        return fail('invalid-materialized-reference', `resulting requirements are invalid: ${requirementsValidation.reason}`);
+    const label = sourceReference.provenance.label;
+    const imported = await importExternalReference(options.imageBytes, {
+        outputLocation: options.outputLocation,
+        ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+        ...(label === undefined ? {} : { label }),
+        supersedesReferenceRoot: options.sourceReferenceRoot,
+        ...(finalRegions.length === 0 ? {} : { regions: finalRegions }),
+        ...(rawRequirements.length === 0 ? {} : { requirements: rawRequirements }),
+        ...(sourceReference.applicability === undefined ? {} : { applicability: sourceReference.applicability }),
+    });
+    if (!imported.ok) {
+        const first = imported.diagnostics[0];
+        const invalidComposition = first !== undefined && ['invalid-reference-region', 'invalid-reference-requirement', 'invalid-reference-applicability'].includes(first.code);
+        return fail(invalidComposition ? 'invalid-materialized-reference' : 'persistence-failure', imported.diagnostics.map((d) => d.message).join('; '));
+    }
+    return {
+        ok: true,
+        referenceId: imported.referenceId,
+        referenceRequestId: imported.referenceRequestId,
+        artifactRoot: imported.artifactRoot,
+        manifestPath: imported.manifestPath,
+        imagePath: imported.imagePath,
+        lifecycle: 'imported',
+        supersedesReferenceId: sourceReference.referenceId,
+        regionCount: imported.regionCount,
+        requirementCount: imported.requirementCount,
+    };
+}
+//# sourceMappingURL=visualAnnotationReferenceMaterializationService.js.map

package/dist/application/visualAnnotationReferenceMaterializationService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualAnnotationReferenceMaterializationService.js","sourceRoot":"","sources":["../../src/application/visualAnnotationReferenceMaterializationService.ts"],"names":[],"mappings":"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"}

package/dist/artifacts/visualAnnotationArtifactReader.d.ts

@@ -0,0 +1,19 @@
+import type { VisualAnnotationArtifact } from '../domain/visualAnnotation.js';
+export type ReadVisualAnnotationArtifactResult = {
+    ok: true;
+    artifact: VisualAnnotationArtifact;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Narrow canonical reader counterpart to
+ * `visualAnnotationArtifactWriter.ts#writeVisualAnnotationArtifact`: reads one
+ * `manifest.json`, parses it, validates it through the same
+ * `isValidVisualAnnotationArtifact` gate the writer uses (never a second
+ * validator), then verifies the owned sibling `annotation-overlay.svg`: it
+ * must be a regular file (lstat, never following a symlink/junction) whose
+ * SHA-256 equals `overlay.sha256`. Read-only: never repairs a manifest, never
+ * regenerates a missing overlay, never accepts an unsupported schema version.
+ */
+export declare function readVisualAnnotationArtifact(manifestPath: string): Promise<ReadVisualAnnotationArtifactResult>;

package/dist/artifacts/visualAnnotationArtifactReader.js

@@ -0,0 +1,66 @@
+import { lstat, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isValidVisualAnnotationArtifact } from '../domain/visualAnnotation.js';
+import { VISUAL_ANNOTATION_OVERLAY_FILENAME, computeVisualAnnotationOverlaySha256 } from './visualAnnotationArtifactWriter.js';
+/**
+ * Narrow canonical reader counterpart to
+ * `visualAnnotationArtifactWriter.ts#writeVisualAnnotationArtifact`: reads one
+ * `manifest.json`, parses it, validates it through the same
+ * `isValidVisualAnnotationArtifact` gate the writer uses (never a second
+ * validator), then verifies the owned sibling `annotation-overlay.svg`: it
+ * must be a regular file (lstat, never following a symlink/junction) whose
+ * SHA-256 equals `overlay.sha256`. Read-only: never repairs a manifest, never
+ * regenerates a missing overlay, never accepts an unsupported schema version.
+ */
+export async function readVisualAnnotationArtifact(manifestPath) {
+    let raw;
+    try {
+        raw = await readFile(manifestPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `failed to read visual-annotation artifact manifest at "${manifestPath}": ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `visual-annotation artifact manifest at "${manifestPath}" is not valid JSON: ${message}` };
+    }
+    const validation = isValidVisualAnnotationArtifact(parsed);
+    if (!validation.valid) {
+        return { ok: false, reason: `visual-annotation artifact manifest at "${manifestPath}" failed structural validation: ${validation.reason}` };
+    }
+    const artifact = parsed;
+    // The validator already pins overlay.path to the exact owned filename; this re-check keeps the
+    // filesystem resolution below fail-closed even if that contract ever changed.
+    if (artifact.overlay.path !== VISUAL_ANNOTATION_OVERLAY_FILENAME) {
+        return { ok: false, reason: `visual-annotation artifact manifest at "${manifestPath}" references an unsupported overlay path` };
+    }
+    const overlayPath = path.join(path.dirname(manifestPath), VISUAL_ANNOTATION_OVERLAY_FILENAME);
+    try {
+        const info = await lstat(overlayPath);
+        if (!info.isFile()) {
+            return { ok: false, reason: `visual-annotation overlay at "${overlayPath}" is not a regular file` };
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `visual-annotation overlay at "${overlayPath}" is missing: ${message}` };
+    }
+    let overlayBytes;
+    try {
+        overlayBytes = await readFile(overlayPath);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, reason: `failed to read visual-annotation overlay at "${overlayPath}": ${message}` };
+    }
+    if (computeVisualAnnotationOverlaySha256(overlayBytes) !== artifact.overlay.sha256) {
+        return { ok: false, reason: `visual-annotation overlay at "${overlayPath}" does not match overlay.sha256` };
+    }
+    return { ok: true, artifact };
+}
+//# sourceMappingURL=visualAnnotationArtifactReader.js.map

package/dist/artifacts/visualAnnotationArtifactReader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualAnnotationArtifactReader.js","sourceRoot":"","sources":["../../src/artifacts/visualAnnotationArtifactReader.ts"],"names":[],"mappings":"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"}

package/dist/artifacts/visualAnnotationArtifactWriter.d.ts

@@ -0,0 +1,42 @@
+import type { VisualAnnotationArtifact } from '../domain/visualAnnotation.js';
+import type { Diagnostic } from '../domain/diagnostics.js';
+export declare const VISUAL_ANNOTATION_MANIFEST_FILENAME = "manifest.json";
+export declare const VISUAL_ANNOTATION_OVERLAY_FILENAME: "annotation-overlay.svg";
+/**
+ * Observer-owned result of persisting one VisualAnnotationArtifact. Mirrors
+ * PersistedExternalReferenceResult's shape: the artifact directory owns
+ * exactly manifest.json and its derived annotation-overlay.svg.
+ */
+export type PersistedVisualAnnotationResult = {
+    ok: true;
+    artifactRoot: string;
+    manifestPath: string;
+    overlayPath: string;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+export interface WriteVisualAnnotationArtifactOptions {
+    /** Base directory that `outputLocation` is resolved against. Defaults to `process.cwd()`. */
+    cwd?: string;
+}
+/** SHA-256 lowercase hex over the exact UTF-8 bytes of an overlay SVG - shared by the writer, reader, and persistence service. */
+export declare function computeVisualAnnotationOverlaySha256(overlay: string | Uint8Array): string;
+/**
+ * Persists one already-assembled VisualAnnotationArtifact as one portable
+ * artifact directory: `<outputLocation>/<annotationId>/{annotation-overlay.svg,manifest.json}`.
+ *
+ * The overlay is always re-derived here through the one canonical renderer
+ * (`domain/visualAnnotation.ts#renderVisualAnnotationOverlaySvg`) and its
+ * digest must equal `artifact.overlay.sha256`; a mismatch is refused rather
+ * than persisted. Never reads or copies the source observation screenshot or
+ * reference image.
+ *
+ * `annotationId` is fresh per persisted instance, so an existing directory at
+ * the final path is treated as a genuine collision and refused rather than
+ * overwritten. Writing happens in a sibling temporary directory
+ * (`.tmp-<annotationId>`), owned overlay media before manifest.json
+ * (manifest-last), and the whole directory is exposed under its real name
+ * only via one atomic rename. The temporary directory is removed on failure.
+ */
+export declare function writeVisualAnnotationArtifact(artifact: VisualAnnotationArtifact, outputLocation: string, options?: WriteVisualAnnotationArtifactOptions): Promise<PersistedVisualAnnotationResult>;

package/dist/artifacts/visualAnnotationArtifactWriter.js

@@ -0,0 +1,85 @@
+import { mkdir, writeFile, rename, rm, access } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { isValidVisualAnnotationArtifact, renderVisualAnnotationOverlaySvg, VISUAL_ANNOTATION_OVERLAY_PATH } from '../domain/visualAnnotation.js';
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+export const VISUAL_ANNOTATION_MANIFEST_FILENAME = 'manifest.json';
+export const VISUAL_ANNOTATION_OVERLAY_FILENAME = VISUAL_ANNOTATION_OVERLAY_PATH;
+/** SHA-256 lowercase hex over the exact UTF-8 bytes of an overlay SVG - shared by the writer, reader, and persistence service. */
+export function computeVisualAnnotationOverlaySha256(overlay) {
+    return createHash('sha256')
+        .update(typeof overlay === 'string' ? Buffer.from(overlay, 'utf8') : overlay)
+        .digest('hex');
+}
+function writeFailure(message, details) {
+    const diagnostic = {
+        code: 'artifact-write-failure',
+        severity: DIAGNOSTIC_SEVERITY['artifact-write-failure'],
+        message,
+        ...(details === undefined ? {} : { details }),
+    };
+    return { ok: false, diagnostics: [diagnostic] };
+}
+async function pathExists(candidate) {
+    return access(candidate).then(() => true, () => false);
+}
+/**
+ * Persists one already-assembled VisualAnnotationArtifact as one portable
+ * artifact directory: `<outputLocation>/<annotationId>/{annotation-overlay.svg,manifest.json}`.
+ *
+ * The overlay is always re-derived here through the one canonical renderer
+ * (`domain/visualAnnotation.ts#renderVisualAnnotationOverlaySvg`) and its
+ * digest must equal `artifact.overlay.sha256`; a mismatch is refused rather
+ * than persisted. Never reads or copies the source observation screenshot or
+ * reference image.
+ *
+ * `annotationId` is fresh per persisted instance, so an existing directory at
+ * the final path is treated as a genuine collision and refused rather than
+ * overwritten. Writing happens in a sibling temporary directory
+ * (`.tmp-<annotationId>`), owned overlay media before manifest.json
+ * (manifest-last), and the whole directory is exposed under its real name
+ * only via one atomic rename. The temporary directory is removed on failure.
+ */
+export async function writeVisualAnnotationArtifact(artifact, outputLocation, options = {}) {
+    const validation = isValidVisualAnnotationArtifact(artifact);
+    if (!validation.valid) {
+        return writeFailure(`refusing to persist an invalid VisualAnnotationArtifact: ${validation.reason}`);
+    }
+    const overlaySvg = renderVisualAnnotationOverlaySvg(artifact.source, artifact.items);
+    const overlayBytes = Buffer.from(overlaySvg, 'utf8');
+    const overlaySha256 = computeVisualAnnotationOverlaySha256(overlayBytes);
+    if (overlaySha256 !== artifact.overlay.sha256) {
+        return writeFailure('refusing to persist a VisualAnnotationArtifact whose overlay.sha256 does not match the deterministically rendered overlay', {
+            expectedSha256: overlaySha256,
+            declaredSha256: artifact.overlay.sha256,
+        });
+    }
+    const cwd = options.cwd ?? process.cwd();
+    const outputRoot = path.resolve(cwd, outputLocation);
+    const finalRoot = path.join(outputRoot, artifact.annotationId);
+    const tempRoot = path.join(outputRoot, `.tmp-${artifact.annotationId}`);
+    if (await pathExists(finalRoot)) {
+        return writeFailure(`a visual-annotation artifact already exists at "${artifact.annotationId}"; refusing to overwrite it`, {
+            artifactRoot: finalRoot,
+        });
+    }
+    try {
+        await rm(tempRoot, { recursive: true, force: true });
+        await mkdir(tempRoot, { recursive: true });
+        await writeFile(path.join(tempRoot, VISUAL_ANNOTATION_OVERLAY_FILENAME), overlayBytes);
+        await writeFile(path.join(tempRoot, VISUAL_ANNOTATION_MANIFEST_FILENAME), JSON.stringify(artifact, null, 2), 'utf8');
+        await rename(tempRoot, finalRoot);
+        return {
+            ok: true,
+            artifactRoot: finalRoot,
+            manifestPath: path.join(finalRoot, VISUAL_ANNOTATION_MANIFEST_FILENAME),
+            overlayPath: path.join(finalRoot, VISUAL_ANNOTATION_OVERLAY_FILENAME),
+        };
+    }
+    catch (err) {
+        await rm(tempRoot, { recursive: true, force: true }).catch(() => undefined);
+        const message = err instanceof Error ? err.message : String(err);
+        return writeFailure(`failed to persist visual-annotation artifact: ${message}`);
+    }
+}
+//# sourceMappingURL=visualAnnotationArtifactWriter.js.map

package/dist/artifacts/visualAnnotationArtifactWriter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visualAnnotationArtifactWriter.js","sourceRoot":"","sources":["../../src/artifacts/visualAnnotationArtifactWriter.ts"],"names":[],"mappings":"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"}