@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/dist/viewer/index.html

@@ -6,8 +6,8 @@
     <meta name="theme-color" content="#0f172a" />
     <title>my-frontend-observer Viewer</title>
     <link rel="icon" type="image/png" href="/icons/icon-192.png" />
-    <script type="module" crossorigin src="/assets/index-D98S1_2d.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CN_yb9Uf.css">
+    <script type="module" crossorigin src="/assets/index-CkKXnlrI.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BN41MI7m.css">
   <link rel="manifest" href="/manifest.webmanifest"><script id="vite-plugin-pwa:register-sw" src="/registerSW.js"></script></head>
   <body>
     <div id="root"></div>

package/dist/viewer/sw.js

@@ -1 +1 @@
-if(!self.define){let e,i={};const n=(n,s)=>(n=new URL(n+".js",s).href,i[n]||new Promise(i=>{if("document"in self){const e=document.createElement("script");e.src=n,e.onload=i,document.head.appendChild(e)}else e=n,importScripts(n),i()}).then(()=>{let e=i[n];if(!e)throw new Error(`Module ${n} didn’t register its module`);return e}));self.define=(s,r)=>{const o=e||("document"in self?document.currentScript.src:"")||location.href;if(i[o])return;let c={};const t=e=>n(e,o),d={module:{uri:o},exports:c,require:t};i[o]=Promise.all(s.map(e=>d[e]||t(e))).then(e=>(r(...e),c))}}define(["./workbox-9c191d2f"],function(e){"use strict";self.skipWaiting(),e.clientsClaim(),e.precacheAndRoute([{url:"registerSW.js",revision:"1872c500de691dce40960bb85481de07"},{url:"manifest.webmanifest",revision:"230563056861fe6705b913b3df23b258"},{url:"index.html",revision:"5cb88d42b2c80bd6eb33a9928a9463d9"},{url:"icons/icon-512.png",revision:"e92e70cceb9b8d7f52ea0cfe9099e7de"},{url:"icons/icon-192.png",revision:"175e5f2a92d509b08ccf2a917bb400f6"},{url:"assets/index-D98S1_2d.js",revision:null},{url:"assets/index-CN_yb9Uf.css",revision:null},{url:"icons/icon-192.png",revision:"175e5f2a92d509b08ccf2a917bb400f6"},{url:"icons/icon-512.png",revision:"e92e70cceb9b8d7f52ea0cfe9099e7de"},{url:"manifest.webmanifest",revision:"230563056861fe6705b913b3df23b258"}],{}),e.cleanupOutdatedCaches(),e.registerRoute(new e.NavigationRoute(e.createHandlerBoundToURL("index.html"),{denylist:[/^\/api\//]}))});
+if(!self.define){let e,i={};const n=(n,s)=>(n=new URL(n+".js",s).href,i[n]||new Promise(i=>{if("document"in self){const e=document.createElement("script");e.src=n,e.onload=i,document.head.appendChild(e)}else e=n,importScripts(n),i()}).then(()=>{let e=i[n];if(!e)throw new Error(`Module ${n} didn’t register its module`);return e}));self.define=(s,r)=>{const o=e||("document"in self?document.currentScript.src:"")||location.href;if(i[o])return;let c={};const t=e=>n(e,o),d={module:{uri:o},exports:c,require:t};i[o]=Promise.all(s.map(e=>d[e]||t(e))).then(e=>(r(...e),c))}}define(["./workbox-9c191d2f"],function(e){"use strict";self.skipWaiting(),e.clientsClaim(),e.precacheAndRoute([{url:"registerSW.js",revision:"1872c500de691dce40960bb85481de07"},{url:"manifest.webmanifest",revision:"230563056861fe6705b913b3df23b258"},{url:"index.html",revision:"5f6a87e03f6fdecdd8e252d369d5d9f1"},{url:"icons/icon-512.png",revision:"e92e70cceb9b8d7f52ea0cfe9099e7de"},{url:"icons/icon-192.png",revision:"175e5f2a92d509b08ccf2a917bb400f6"},{url:"assets/index-CkKXnlrI.js",revision:null},{url:"assets/index-BN41MI7m.css",revision:null},{url:"icons/icon-192.png",revision:"175e5f2a92d509b08ccf2a917bb400f6"},{url:"icons/icon-512.png",revision:"e92e70cceb9b8d7f52ea0cfe9099e7de"},{url:"manifest.webmanifest",revision:"230563056861fe6705b913b3df23b258"}],{}),e.cleanupOutdatedCaches(),e.registerRoute(new e.NavigationRoute(e.createHandlerBoundToURL("index.html"),{denylist:[/^\/api\//]}))});

package/dist/viewerServer/annotationAuthoring.d.ts

@@ -0,0 +1,64 @@
+import type { VisualAnnotationItem, VisualAnnotationSource } from '../domain/visualAnnotation.js';
+import type { ViewerAuthoringSession } from './authoringSecurity.js';
+/**
+ * v0.9 Batch 2 closed save request. The browser supplies only viewer handles
+ * and annotation items. Source identity, output location, project root,
+ * annotation identity, overlay metadata, timestamps, and producer metadata
+ * are always server/application owned.
+ */
+export interface SaveAnnotationRequest {
+    sourceHandle: string;
+    parentAnnotationHandle?: string;
+    items: VisualAnnotationItem[];
+}
+export type ParseSaveAnnotationRequestResult = {
+    ok: true;
+    request: SaveAnnotationRequest;
+} | {
+    ok: false;
+    error: string;
+};
+/** Maximum number of annotation item ids accepted by one promotion or materialization request. */
+export declare const MAX_AUTHORING_ITEM_IDS = 100;
+/**
+ * v0.9 Batch 5/6 shared `itemIds` shape rule for authoring requests that act on
+ * selected items of a saved annotation: a non-empty array of at most 100
+ * unique, non-empty strings.
+ */
+export declare function parseAuthoringItemIds(value: unknown): {
+    ok: true;
+    itemIds: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Request-shape validation only. Item content is validated later by the canonical visual-annotation domain. */
+export declare function parseSaveAnnotationRequest(value: unknown): ParseSaveAnnotationRequestResult;
+/**
+ * Exact canonical source equality: every persisted source identity field must
+ * match. Never a logical-id-only comparison, never alias or filesystem based.
+ */
+export declare function isSameVisualAnnotationSource(a: VisualAnnotationSource, b: VisualAnnotationSource): boolean;
+export type SaveAnnotationFailureReason = 'unknown-source-handle' | 'source-not-loadable' | 'source-not-annotatable' | 'unknown-parent-handle' | 'parent-not-annotation' | 'parent-source-mismatch' | 'parent-has-child' | 'revision-lineage-unverifiable' | 'invalid-annotation' | 'persistence-failed';
+export type SaveAnnotationResult = {
+    ok: true;
+    annotationId: string;
+    annotationRequestId: string;
+    handle: string;
+} | {
+    ok: false;
+    reason: SaveAnnotationFailureReason;
+    error: string;
+};
+/** v0.9 Batch 5: runs one authoring write through the session's single in-process write queue. */
+export declare function runSerializedAuthoringWrite<T>(session: ViewerAuthoringSession, write: () => Promise<T>): Promise<T>;
+/**
+ * The one v0.9 Batch 2 viewer save use case. Resolves the source (and optional
+ * parent) through the canonical handle boundary, constructs the canonical
+ * annotation source server-side, enforces the same-source and stale-revision
+ * rules, and then persists exactly once through `persistVisualAnnotation`
+ * into the project-managed annotation location. It never writes directly,
+ * never builds identity or overlays itself, and never returns filesystem
+ * paths.
+ */
+export declare function saveAnnotationFromViewer(root: string, session: ViewerAuthoringSession, request: SaveAnnotationRequest): Promise<SaveAnnotationResult>;

package/dist/viewerServer/annotationAuthoring.js

@@ -0,0 +1,230 @@
+import { persistVisualAnnotation } from '../application/visualAnnotationPersistenceService.js';
+import { annotationOutputLocation } from '../projectWorkflow/projectPaths.js';
+import { loadArtifactByHandle } from './evidence/index.js';
+import { discoverManifests } from './evidence/discovery.js';
+import { classifyManifest } from './evidence/classify.js';
+import { encodeArtifactHandle } from './evidence/handles.js';
+import { MAX_INDEX_RECORDS } from './evidence/limits.js';
+const SAVE_REQUEST_KEYS = ['sourceHandle', 'parentAnnotationHandle', 'items'];
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/** Maximum number of annotation item ids accepted by one promotion or materialization request. */
+export const MAX_AUTHORING_ITEM_IDS = 100;
+/**
+ * v0.9 Batch 5/6 shared `itemIds` shape rule for authoring requests that act on
+ * selected items of a saved annotation: a non-empty array of at most 100
+ * unique, non-empty strings.
+ */
+export function parseAuthoringItemIds(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return { ok: false, error: 'itemIds must be a non-empty array' };
+    if (value.length > MAX_AUTHORING_ITEM_IDS)
+        return { ok: false, error: `itemIds must contain at most ${MAX_AUTHORING_ITEM_IDS} entries` };
+    if (!value.every((id) => typeof id === 'string' && id.length > 0))
+        return { ok: false, error: 'every itemIds entry must be a non-empty string' };
+    if (new Set(value).size !== value.length)
+        return { ok: false, error: 'itemIds must be unique' };
+    return { ok: true, itemIds: value };
+}
+/** Request-shape validation only. Item content is validated later by the canonical visual-annotation domain. */
+export function parseSaveAnnotationRequest(value) {
+    if (!isPlainObject(value))
+        return { ok: false, error: 'request body must be a JSON object' };
+    const unknownKeys = Object.keys(value).filter((key) => !SAVE_REQUEST_KEYS.includes(key));
+    if (unknownKeys.length > 0)
+        return { ok: false, error: `unsupported request field(s): ${unknownKeys.slice(0, 10).join(', ')}` };
+    if (!isNonEmptyString(value.sourceHandle))
+        return { ok: false, error: 'sourceHandle must be a non-empty string' };
+    if ('parentAnnotationHandle' in value && !isNonEmptyString(value.parentAnnotationHandle)) {
+        return { ok: false, error: 'parentAnnotationHandle must be a non-empty string when present' };
+    }
+    if (!Array.isArray(value.items))
+        return { ok: false, error: 'items must be an array' };
+    return {
+        ok: true,
+        request: {
+            sourceHandle: value.sourceHandle,
+            ...(typeof value.parentAnnotationHandle === 'string' ? { parentAnnotationHandle: value.parentAnnotationHandle } : {}),
+            items: value.items,
+        },
+    };
+}
+/**
+ * Exact canonical source equality: every persisted source identity field must
+ * match. Never a logical-id-only comparison, never alias or filesystem based.
+ */
+export function isSameVisualAnnotationSource(a, b) {
+    if (a.kind === 'runtime-observation' && b.kind === 'runtime-observation') {
+        return (a.observationId === b.observationId &&
+            a.requestId === b.requestId &&
+            a.observationSchemaVersion === b.observationSchemaVersion &&
+            a.screenshot.path === b.screenshot.path &&
+            a.coordinateSpace.kind === b.coordinateSpace.kind &&
+            a.coordinateSpace.width === b.coordinateSpace.width &&
+            a.coordinateSpace.height === b.coordinateSpace.height);
+    }
+    if (a.kind === 'external-reference' && b.kind === 'external-reference') {
+        return (a.referenceId === b.referenceId &&
+            a.referenceRequestId === b.referenceRequestId &&
+            a.referenceSchemaVersion === b.referenceSchemaVersion &&
+            a.lifecycle === b.lifecycle &&
+            a.imageOwnerReferenceId === b.imageOwnerReferenceId &&
+            a.imageSha256 === b.imageSha256 &&
+            a.coordinateSpace.kind === b.coordinateSpace.kind &&
+            a.coordinateSpace.width === b.coordinateSpace.width &&
+            a.coordinateSpace.height === b.coordinateSpace.height);
+    }
+    return false;
+}
+/** Builds the canonical annotation source from an already-loaded, already-validated artifact. Runtime frames are viewport CSS pixels, never screenshot device pixels. */
+function buildAnnotationSource(detail) {
+    const { family, artifact } = detail;
+    if (family === 'observation' && 'observationId' in artifact) {
+        const screenshot = artifact.screenshot;
+        if (screenshot.state !== 'available' && screenshot.state !== 'partial') {
+            return { ok: false, error: 'the source observation has no recorded screenshot to annotate' };
+        }
+        return {
+            ok: true,
+            source: {
+                kind: 'runtime-observation',
+                observationId: artifact.observationId,
+                requestId: artifact.requestId,
+                observationSchemaVersion: artifact.schemaVersion,
+                screenshot: { path: screenshot.value.path },
+                coordinateSpace: { kind: 'runtime-css-px', width: artifact.requestConfig.viewport.width, height: artifact.requestConfig.viewport.height },
+            },
+        };
+    }
+    if (family === 'external-reference-imported' && 'referenceId' in artifact && 'image' in artifact) {
+        return {
+            ok: true,
+            source: {
+                kind: 'external-reference',
+                referenceId: artifact.referenceId,
+                referenceRequestId: artifact.referenceRequestId,
+                referenceSchemaVersion: artifact.schemaVersion,
+                lifecycle: 'imported',
+                imageOwnerReferenceId: artifact.referenceId,
+                imageSha256: artifact.image.sha256,
+                coordinateSpace: { kind: 'reference-image-px', width: artifact.image.width, height: artifact.image.height },
+            },
+        };
+    }
+    if (family === 'external-reference-approved' && 'referenceId' in artifact && 'sourceReference' in artifact) {
+        return {
+            ok: true,
+            source: {
+                kind: 'external-reference',
+                referenceId: artifact.referenceId,
+                referenceRequestId: artifact.referenceRequestId,
+                referenceSchemaVersion: artifact.schemaVersion,
+                lifecycle: 'approved',
+                imageOwnerReferenceId: artifact.sourceReference.referenceId,
+                imageSha256: artifact.sourceReference.image.sha256,
+                coordinateSpace: { kind: 'reference-image-px', width: artifact.sourceReference.image.width, height: artifact.sourceReference.image.height },
+            },
+        };
+    }
+    return { ok: false, error: `"${family}" evidence cannot be annotated; only observations and external references can` };
+}
+/**
+ * Bounded stale-revision scan: does any currently supported visual annotation
+ * already supersede `parentAnnotationId`? Uses the same bounded discovery and
+ * canonical classification as the index. If discovery was truncated the
+ * lineage cannot be proven child-free, so the caller fails closed.
+ */
+async function scanForExistingChild(root, parentAnnotationId) {
+    const discovery = await discoverManifests(root);
+    for (const manifest of discovery.manifests.slice(0, MAX_INDEX_RECORDS)) {
+        const classified = await classifyManifest(manifest.absolutePath);
+        if (classified.supportState !== 'supported' || classified.family !== 'visual-annotation')
+            continue;
+        if (classified.artifact.supersedesAnnotationId === parentAnnotationId)
+            return { status: 'has-child' };
+    }
+    if (discovery.truncated || discovery.manifests.length > MAX_INDEX_RECORDS)
+        return { status: 'unverifiable' };
+    return { status: 'none' };
+}
+/** One in-process authoring write at a time per session, so read-check-write sequences (stale revisions, contract promotion and activation) cannot interleave. */
+const saveQueues = new WeakMap();
+/** v0.9 Batch 5: runs one authoring write through the session's single in-process write queue. */
+export function runSerializedAuthoringWrite(session, write) {
+    const previous = saveQueues.get(session) ?? Promise.resolve();
+    const next = previous.then(write, write);
+    saveQueues.set(session, next);
+    return next;
+}
+/**
+ * The one v0.9 Batch 2 viewer save use case. Resolves the source (and optional
+ * parent) through the canonical handle boundary, constructs the canonical
+ * annotation source server-side, enforces the same-source and stale-revision
+ * rules, and then persists exactly once through `persistVisualAnnotation`
+ * into the project-managed annotation location. It never writes directly,
+ * never builds identity or overlays itself, and never returns filesystem
+ * paths.
+ */
+export function saveAnnotationFromViewer(root, session, request) {
+    return runSerializedAuthoringWrite(session, () => performSave(root, session, request));
+}
+async function performSave(root, session, request) {
+    const sourceLoaded = await loadArtifactByHandle(root, request.sourceHandle);
+    if (!sourceLoaded.ok) {
+        return sourceLoaded.reason === 'unknown-handle'
+            ? { ok: false, reason: 'unknown-source-handle', error: 'unknown source evidence handle' }
+            : { ok: false, reason: 'source-not-loadable', error: 'source evidence is not currently loadable' };
+    }
+    const built = buildAnnotationSource(sourceLoaded.detail);
+    if (!built.ok)
+        return { ok: false, reason: 'source-not-annotatable', error: built.error };
+    const source = built.source;
+    let supersedesAnnotationId;
+    if (request.parentAnnotationHandle !== undefined) {
+        const parentLoaded = await loadArtifactByHandle(root, request.parentAnnotationHandle);
+        if (!parentLoaded.ok) {
+            return parentLoaded.reason === 'unknown-handle'
+                ? { ok: false, reason: 'unknown-parent-handle', error: 'unknown parent annotation handle' }
+                : { ok: false, reason: 'parent-not-annotation', error: 'parent annotation is not currently loadable visual-annotation evidence' };
+        }
+        if (parentLoaded.detail.family !== 'visual-annotation' || !('annotationId' in parentLoaded.detail.artifact)) {
+            return { ok: false, reason: 'parent-not-annotation', error: 'parentAnnotationHandle does not name visual-annotation evidence' };
+        }
+        const parent = parentLoaded.detail.artifact;
+        if (!isSameVisualAnnotationSource(parent.source, source)) {
+            return { ok: false, reason: 'parent-source-mismatch', error: 'the parent annotation was made over a different canonical source' };
+        }
+        const childScan = await scanForExistingChild(root, parent.annotationId);
+        if (childScan.status === 'has-child') {
+            return { ok: false, reason: 'parent-has-child', error: 'the parent annotation already has a saved revision; reload before revising' };
+        }
+        if (childScan.status === 'unverifiable') {
+            return { ok: false, reason: 'revision-lineage-unverifiable', error: 'the evidence root is too large to verify that the parent annotation has no saved revision' };
+        }
+        supersedesAnnotationId = parent.annotationId;
+    }
+    const persisted = await persistVisualAnnotation({
+        source,
+        items: request.items,
+        outputLocation: annotationOutputLocation(),
+        cwd: session.projectRoot,
+        ...(supersedesAnnotationId === undefined ? {} : { supersedesAnnotationId }),
+    });
+    if (!persisted.ok) {
+        const first = persisted.diagnostics[0];
+        if (first?.code === 'invalid-request')
+            return { ok: false, reason: 'invalid-annotation', error: first.message };
+        return { ok: false, reason: 'persistence-failed', error: 'the annotation could not be persisted' };
+    }
+    return {
+        ok: true,
+        annotationId: persisted.annotationId,
+        annotationRequestId: persisted.annotationRequestId,
+        handle: encodeArtifactHandle('visual-annotation', `annotations/${persisted.annotationId}`),
+    };
+}
+//# sourceMappingURL=annotationAuthoring.js.map

package/dist/viewerServer/annotationAuthoring.js.map

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

package/dist/viewerServer/annotationContractPromotion.d.ts

@@ -0,0 +1,51 @@
+import type { PromoteVisualAnnotationContractFailureCode } from '../application/visualAnnotationContractPromotionService.js';
+import type { ViewerAuthoringSession } from './authoringSecurity.js';
+/** v0.9 Batch 5 closed promotion request. The browser supplies only annotation item ids and the explicit activation choice. */
+export interface PromoteAnnotationContractRequest {
+    itemIds: string[];
+    activateForCheck: boolean;
+}
+export type ParsePromoteAnnotationContractRequestResult = {
+    ok: true;
+    request: PromoteAnnotationContractRequest;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parsePromoteAnnotationContractRequest(value: unknown): ParsePromoteAnnotationContractRequestResult;
+export type ContractActivation = {
+    state: 'not-requested';
+} | {
+    state: 'activated';
+} | {
+    state: 'not-configured';
+    reason: string;
+} | {
+    state: 'failed';
+    reason: string;
+};
+export type PromoteAnnotationContractFailureReason = 'unknown-annotation-handle' | 'not-an-annotation' | 'reference-annotation' | 'source-unavailable' | 'project-config-invalid' | 'configured-baseline-invalid' | PromoteVisualAnnotationContractFailureCode;
+export type PromoteAnnotationContractFromViewerResult = {
+    ok: true;
+    contractId: string;
+    contractRequestId: string;
+    handle: string;
+    clauseCount: number;
+    activation: ContractActivation;
+} | {
+    ok: false;
+    reason: PromoteAnnotationContractFailureReason;
+    error: string;
+};
+/**
+ * v0.9 Batch 5 viewer promotion use case (`POST
+ * /api/annotations/:handle/promote-contract`). Resolves the saved annotation
+ * and its exact canonical source observation, derives `activeBaselineIds`
+ * only from an explicitly configured and valid baseline contract, then calls
+ * the canonical `promoteVisualAnnotationContract` exactly once. Activation for
+ * project `check` happens only when requested, and only through
+ * `activateProjectChangeContract`; an activation failure never undoes the
+ * persisted contract. Runs through the session's single authoring write
+ * queue. Never returns filesystem paths.
+ */
+export declare function promoteAnnotationContractFromViewer(root: string, session: ViewerAuthoringSession, annotationHandle: string, request: PromoteAnnotationContractRequest): Promise<PromoteAnnotationContractFromViewerResult>;

package/dist/viewerServer/annotationContractPromotion.js

@@ -0,0 +1,105 @@
+import path from 'node:path';
+import { readProjectConfig } from '../projectWorkflow/projectConfig.js';
+import { contractOutputLocation, projectConfigPath } from '../projectWorkflow/projectPaths.js';
+import { resolveContainedAcceptancePath } from '../projectWorkflow/checkAcceptance.js';
+import { readPersistentBaselineContract } from '../artifacts/frontendContractArtifactReader.js';
+import { promoteVisualAnnotationContract } from '../application/visualAnnotationContractPromotionService.js';
+import { activateProjectChangeContract } from '../application/projectWorkflowService.js';
+import { getAnnotationView } from './evidence/annotationView.js';
+import { loadArtifactByHandle } from './evidence/index.js';
+import { encodeArtifactHandle } from './evidence/handles.js';
+import { parseAuthoringItemIds, runSerializedAuthoringWrite } from './annotationAuthoring.js';
+const PROMOTE_REQUEST_KEYS = ['itemIds', 'activateForCheck'];
+export function parsePromoteAnnotationContractRequest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return { ok: false, error: 'request body must be a JSON object' };
+    const record = value;
+    const unknownKeys = Object.keys(record).filter((key) => !PROMOTE_REQUEST_KEYS.includes(key));
+    if (unknownKeys.length > 0)
+        return { ok: false, error: `unsupported request field(s): ${unknownKeys.slice(0, 10).join(', ')}` };
+    const itemIds = parseAuthoringItemIds(record.itemIds);
+    if (!itemIds.ok)
+        return itemIds;
+    if (typeof record.activateForCheck !== 'boolean')
+        return { ok: false, error: 'activateForCheck must be a boolean' };
+    return { ok: true, request: { itemIds: itemIds.itemIds, activateForCheck: record.activateForCheck } };
+}
+const MAX_ACTIVATION_REASON_LENGTH = 300;
+/**
+ * v0.9 Batch 5 viewer promotion use case (`POST
+ * /api/annotations/:handle/promote-contract`). Resolves the saved annotation
+ * and its exact canonical source observation, derives `activeBaselineIds`
+ * only from an explicitly configured and valid baseline contract, then calls
+ * the canonical `promoteVisualAnnotationContract` exactly once. Activation for
+ * project `check` happens only when requested, and only through
+ * `activateProjectChangeContract`; an activation failure never undoes the
+ * persisted contract. Runs through the session's single authoring write
+ * queue. Never returns filesystem paths.
+ */
+export function promoteAnnotationContractFromViewer(root, session, annotationHandle, request) {
+    return runSerializedAuthoringWrite(session, () => performPromotion(root, session, annotationHandle, request));
+}
+async function performPromotion(root, session, annotationHandle, request) {
+    const view = await getAnnotationView(root, annotationHandle);
+    if (!view.ok) {
+        return view.reason === 'unknown-handle'
+            ? { ok: false, reason: 'unknown-annotation-handle', error: 'unknown annotation handle' }
+            : { ok: false, reason: 'not-an-annotation', error: 'the handle does not name loadable visual-annotation evidence' };
+    }
+    const { annotation, source } = view;
+    if (annotation.source.kind !== 'runtime-observation') {
+        return { ok: false, reason: 'reference-annotation', error: 'external-reference annotations are not promoted into frontend change contracts' };
+    }
+    if (source.status !== 'available' || source.family !== 'observation') {
+        return { ok: false, reason: 'source-unavailable', error: 'the annotation source observation is not uniquely available in this evidence root' };
+    }
+    const sourceLoaded = await loadArtifactByHandle(root, source.handle);
+    if (!sourceLoaded.ok || sourceLoaded.detail.family !== 'observation') {
+        return { ok: false, reason: 'source-unavailable', error: 'the annotation source observation is no longer loadable' };
+    }
+    const sourceObservation = sourceLoaded.detail.artifact;
+    const config = await readProjectConfig(projectConfigPath(session.projectRoot));
+    if (!config.ok)
+        return { ok: false, reason: 'project-config-invalid', error: 'the project configuration is invalid' };
+    const contractAcceptance = config.config.acceptance?.contract;
+    let activeBaselineIds = [];
+    if (contractAcceptance !== undefined) {
+        const baselineRoot = resolveContainedAcceptancePath(session.projectRoot, contractAcceptance.baselineArtifact);
+        if (!baselineRoot.ok)
+            return { ok: false, reason: 'configured-baseline-invalid', error: 'the configured baseline contract path is missing or outside the project' };
+        const baseline = await readPersistentBaselineContract(path.join(baselineRoot.path, 'manifest.json'));
+        if (!baseline.ok)
+            return { ok: false, reason: 'configured-baseline-invalid', error: 'the configured baseline contract is missing or invalid' };
+        activeBaselineIds = [baseline.contract.baselineId];
+    }
+    const promoted = await promoteVisualAnnotationContract({
+        annotation,
+        sourceObservation,
+        selectedItemIds: request.itemIds,
+        activeBaselineIds,
+        outputLocation: contractOutputLocation(),
+        cwd: session.projectRoot,
+    });
+    if (!promoted.ok) {
+        return { ok: false, reason: promoted.code, error: promoted.code === 'persistence-failed' ? 'the change contract could not be persisted' : promoted.reason };
+    }
+    let activation = { state: 'not-requested' };
+    if (request.activateForCheck) {
+        const activated = await activateProjectChangeContract(session.projectRoot, `${contractOutputLocation()}/${promoted.contractId}`);
+        if (activated.ok)
+            activation = { state: 'activated' };
+        else if (activated.code === 'not-configured')
+            activation = { state: 'not-configured', reason: activated.reason };
+        else
+            activation = { state: 'failed', reason: `The change contract was persisted, but project activation failed (${activated.code}).`.slice(0, MAX_ACTIVATION_REASON_LENGTH) };
+    }
+    return {
+        ok: true,
+        contractId: promoted.contractId,
+        contractRequestId: promoted.contractRequestId,
+        handle: encodeArtifactHandle('change-contract', `contracts/${promoted.contractId}`),
+        clauseCount: promoted.clauseCount,
+        activation,
+    };
+}
+//# sourceMappingURL=annotationContractPromotion.js.map

package/dist/viewerServer/annotationContractPromotion.js.map

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

package/dist/viewerServer/annotationReferenceMaterialization.d.ts

@@ -0,0 +1,40 @@
+import type { MaterializeVisualAnnotationReferenceFailureCode } from '../application/visualAnnotationReferenceMaterializationService.js';
+import type { ViewerAuthoringSession } from './authoringSecurity.js';
+/** v0.9 Batch 6 closed materialization request. The browser supplies only the selected annotation item ids. */
+export interface MaterializeAnnotationReferenceRequest {
+    itemIds: string[];
+}
+export type ParseMaterializeAnnotationReferenceRequestResult = {
+    ok: true;
+    request: MaterializeAnnotationReferenceRequest;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseMaterializeAnnotationReferenceRequest(value: unknown): ParseMaterializeAnnotationReferenceRequestResult;
+export type MaterializeAnnotationReferenceFailureReason = 'unknown-annotation-handle' | 'not-an-annotation' | 'runtime-annotation' | 'source-unavailable' | 'source-image-unavailable' | 'image-read-failure' | MaterializeVisualAnnotationReferenceFailureCode;
+export type MaterializeAnnotationReferenceFromViewerResult = {
+    ok: true;
+    referenceId: string;
+    referenceRequestId: string;
+    handle: string;
+    supersedesReferenceId: string;
+    regionCount: number;
+    requirementCount: number;
+} | {
+    ok: false;
+    reason: MaterializeAnnotationReferenceFailureReason;
+    error: string;
+};
+/**
+ * v0.9 Batch 6 viewer materialization use case (`POST
+ * /api/annotations/:handle/materialize-reference`). Resolves the saved
+ * external-reference annotation and its exact canonical source reference,
+ * reads the canonical image bytes only through the existing safe media
+ * boundary (`image` for an imported source, `source-image` for an approved
+ * one), resolves the source artifact root from its own viewer handle, and
+ * calls the canonical `materializeVisualAnnotationReference` exactly once.
+ * Runs through the session's single authoring write queue. Never approves,
+ * never touches project configuration, and never returns filesystem paths.
+ */
+export declare function materializeAnnotationReferenceFromViewer(root: string, session: ViewerAuthoringSession, annotationHandle: string, request: MaterializeAnnotationReferenceRequest): Promise<MaterializeAnnotationReferenceFromViewerResult>;

package/dist/viewerServer/annotationReferenceMaterialization.js

@@ -0,0 +1,91 @@
+import { readFile } from 'node:fs/promises';
+import { referenceOutputLocation } from '../projectWorkflow/projectPaths.js';
+import { materializeVisualAnnotationReference } from '../application/visualAnnotationReferenceMaterializationService.js';
+import { getAnnotationView } from './evidence/annotationView.js';
+import { loadArtifactByHandle } from './evidence/index.js';
+import { resolveMedia } from './evidence/mediaResolver.js';
+import { decodeArtifactHandle, encodeArtifactHandle } from './evidence/handles.js';
+import { resolveContainedDir } from './evidence/pathSafety.js';
+import { parseAuthoringItemIds, runSerializedAuthoringWrite } from './annotationAuthoring.js';
+export function parseMaterializeAnnotationReferenceRequest(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return { ok: false, error: 'request body must be a JSON object' };
+    const record = value;
+    const unknownKeys = Object.keys(record).filter((key) => key !== 'itemIds');
+    if (unknownKeys.length > 0)
+        return { ok: false, error: `unsupported request field(s): ${unknownKeys.slice(0, 10).join(', ')}` };
+    const itemIds = parseAuthoringItemIds(record.itemIds);
+    if (!itemIds.ok)
+        return itemIds;
+    return { ok: true, request: { itemIds: itemIds.itemIds } };
+}
+/**
+ * v0.9 Batch 6 viewer materialization use case (`POST
+ * /api/annotations/:handle/materialize-reference`). Resolves the saved
+ * external-reference annotation and its exact canonical source reference,
+ * reads the canonical image bytes only through the existing safe media
+ * boundary (`image` for an imported source, `source-image` for an approved
+ * one), resolves the source artifact root from its own viewer handle, and
+ * calls the canonical `materializeVisualAnnotationReference` exactly once.
+ * Runs through the session's single authoring write queue. Never approves,
+ * never touches project configuration, and never returns filesystem paths.
+ */
+export function materializeAnnotationReferenceFromViewer(root, session, annotationHandle, request) {
+    return runSerializedAuthoringWrite(session, () => performMaterialization(root, session, annotationHandle, request));
+}
+async function performMaterialization(root, session, annotationHandle, request) {
+    const view = await getAnnotationView(root, annotationHandle);
+    if (!view.ok) {
+        return view.reason === 'unknown-handle'
+            ? { ok: false, reason: 'unknown-annotation-handle', error: 'unknown annotation handle' }
+            : { ok: false, reason: 'not-an-annotation', error: 'the handle does not name loadable visual-annotation evidence' };
+    }
+    const { annotation, source } = view;
+    if (annotation.source.kind !== 'external-reference') {
+        return { ok: false, reason: 'runtime-annotation', error: 'runtime-observation annotations are not materialized into external-reference revisions' };
+    }
+    if (source.status !== 'available' || (source.family !== 'external-reference-imported' && source.family !== 'external-reference-approved')) {
+        return { ok: false, reason: 'source-unavailable', error: 'the annotation source reference is not uniquely available in this evidence root' };
+    }
+    const sourceLoaded = await loadArtifactByHandle(root, source.handle);
+    if (!sourceLoaded.ok || sourceLoaded.detail.family !== source.family) {
+        return { ok: false, reason: 'source-unavailable', error: 'the annotation source reference is no longer loadable' };
+    }
+    const sourceReference = sourceLoaded.detail.artifact;
+    const decoded = decodeArtifactHandle(source.handle);
+    const sourceReferenceRoot = decoded.ok ? resolveContainedDir(root, decoded.relativeDir) : undefined;
+    if (sourceReferenceRoot === undefined)
+        return { ok: false, reason: 'source-unavailable', error: 'the annotation source reference directory could not be resolved' };
+    const media = await resolveMedia(root, source.handle, source.family === 'external-reference-approved' ? 'source-image' : 'image');
+    if (!media.ok)
+        return { ok: false, reason: 'source-image-unavailable', error: 'the canonical source reference image is not available' };
+    let imageBytes;
+    try {
+        imageBytes = await readFile(media.absolutePath);
+    }
+    catch {
+        return { ok: false, reason: 'image-read-failure', error: 'the canonical source reference image could not be read' };
+    }
+    const materialized = await materializeVisualAnnotationReference({
+        annotation,
+        sourceReference,
+        sourceReferenceRoot,
+        imageBytes,
+        selectedItemIds: request.itemIds,
+        outputLocation: referenceOutputLocation(),
+        cwd: session.projectRoot,
+    });
+    if (!materialized.ok) {
+        return { ok: false, reason: materialized.code, error: materialized.code === 'persistence-failure' ? 'the reference revision could not be persisted' : materialized.reason };
+    }
+    return {
+        ok: true,
+        referenceId: materialized.referenceId,
+        referenceRequestId: materialized.referenceRequestId,
+        handle: encodeArtifactHandle('external-reference-imported', `references/${materialized.referenceId}`),
+        supersedesReferenceId: materialized.supersedesReferenceId,
+        regionCount: materialized.regionCount,
+        requirementCount: materialized.requirementCount,
+    };
+}
+//# sourceMappingURL=annotationReferenceMaterialization.js.map