@dailephd/my-frontend-observer 0.8.1

package/dist/viewer/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <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">
+  <link rel="manifest" href="/manifest.webmanifest"><script id="vite-plugin-pwa:register-sw" src="/registerSW.js"></script></head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist/viewer/manifest.webmanifest

@@ -0,0 +1 @@
+{"name":"my-frontend-observer Viewer","short_name":"Observer Viewer","description":"Local-first interactive viewer for my-frontend-observer runtime evidence.","start_url":"/","display":"standalone","background_color":"#0f172a","theme_color":"#0f172a","lang":"en","scope":"/","icons":[{"src":"icons/icon-192.png","sizes":"192x192","type":"image/png"},{"src":"icons/icon-512.png","sizes":"512x512","type":"image/png"}]}

package/dist/viewer/registerSW.js

@@ -0,0 +1 @@
+if('serviceWorker' in navigator) {window.addEventListener('load', () => {navigator.serviceWorker.register('/sw.js', { scope: '/' })})}

package/dist/viewer/sw.js

@@ -0,0 +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\//]}))});

package/dist/viewer/workbox-9c191d2f.js

@@ -0,0 +1 @@
+define(["exports"],function(t){"use strict";try{self["workbox:core:7.4.0"]&&_()}catch(t){}const e=(t,...e)=>{let s=t;return e.length>0&&(s+=` :: ${JSON.stringify(e)}`),s};class s extends Error{constructor(t,s){super(e(t,s)),this.name=t,this.details=s}}try{self["workbox:routing:7.4.0"]&&_()}catch(t){}const n=t=>t&&"object"==typeof t?t:{handle:t};class i{constructor(t,e,s="GET"){this.handler=n(e),this.match=t,this.method=s}setCatchHandler(t){this.catchHandler=n(t)}}class r extends i{constructor(t,e,s){super(({url:e})=>{const s=t.exec(e.href);if(s&&(e.origin===location.origin||0===s.index))return s.slice(1)},e,s)}}class o{constructor(){this.t=new Map,this.i=new Map}get routes(){return this.t}addFetchListener(){self.addEventListener("fetch",t=>{const{request:e}=t,s=this.handleRequest({request:e,event:t});s&&t.respondWith(s)})}addCacheListener(){self.addEventListener("message",t=>{if(t.data&&"CACHE_URLS"===t.data.type){const{payload:e}=t.data,s=Promise.all(e.urlsToCache.map(e=>{"string"==typeof e&&(e=[e]);const s=new Request(...e);return this.handleRequest({request:s,event:t})}));t.waitUntil(s),t.ports&&t.ports[0]&&s.then(()=>t.ports[0].postMessage(!0))}})}handleRequest({request:t,event:e}){const s=new URL(t.url,location.href);if(!s.protocol.startsWith("http"))return;const n=s.origin===location.origin,{params:i,route:r}=this.findMatchingRoute({event:e,request:t,sameOrigin:n,url:s});let o=r&&r.handler;const c=t.method;if(!o&&this.i.has(c)&&(o=this.i.get(c)),!o)return;let a;try{a=o.handle({url:s,request:t,event:e,params:i})}catch(t){a=Promise.reject(t)}const h=r&&r.catchHandler;return a instanceof Promise&&(this.o||h)&&(a=a.catch(async n=>{if(h)try{return await h.handle({url:s,request:t,event:e,params:i})}catch(t){t instanceof Error&&(n=t)}if(this.o)return this.o.handle({url:s,request:t,event:e});throw n})),a}findMatchingRoute({url:t,sameOrigin:e,request:s,event:n}){const i=this.t.get(s.method)||[];for(const r of i){let i;const o=r.match({url:t,sameOrigin:e,request:s,event:n});if(o)return i=o,(Array.isArray(i)&&0===i.length||o.constructor===Object&&0===Object.keys(o).length||"boolean"==typeof o)&&(i=void 0),{route:r,params:i}}return{}}setDefaultHandler(t,e="GET"){this.i.set(e,n(t))}setCatchHandler(t){this.o=n(t)}registerRoute(t){this.t.has(t.method)||this.t.set(t.method,[]),this.t.get(t.method).push(t)}unregisterRoute(t){if(!this.t.has(t.method))throw new s("unregister-route-but-not-found-with-method",{method:t.method});const e=this.t.get(t.method).indexOf(t);if(!(e>-1))throw new s("unregister-route-route-not-registered");this.t.get(t.method).splice(e,1)}}let c;const a=()=>(c||(c=new o,c.addFetchListener(),c.addCacheListener()),c);function h(t,e,n){let o;if("string"==typeof t){const s=new URL(t,location.href);o=new i(({url:t})=>t.href===s.href,e,n)}else if(t instanceof RegExp)o=new r(t,e,n);else if("function"==typeof t)o=new i(t,e,n);else{if(!(t instanceof i))throw new s("unsupported-route-type",{moduleName:"workbox-routing",funcName:"registerRoute",paramName:"capture"});o=t}return a().registerRoute(o),o}const u={googleAnalytics:"googleAnalytics",precache:"precache-v2",prefix:"workbox",runtime:"runtime",suffix:"undefined"!=typeof registration?registration.scope:""},l=t=>[u.prefix,t,u.suffix].filter(t=>t&&t.length>0).join("-"),f=t=>t||l(u.precache),w=t=>t||l(u.runtime);function d(t,e){const s=e();return t.waitUntil(s),s}try{self["workbox:precaching:7.4.0"]&&_()}catch(t){}function p(t){if(!t)throw new s("add-to-cache-list-unexpected-type",{entry:t});if("string"==typeof t){const e=new URL(t,location.href);return{cacheKey:e.href,url:e.href}}const{revision:e,url:n}=t;if(!n)throw new s("add-to-cache-list-unexpected-type",{entry:t});if(!e){const t=new URL(n,location.href);return{cacheKey:t.href,url:t.href}}const i=new URL(n,location.href),r=new URL(n,location.href);return i.searchParams.set("__WB_REVISION__",e),{cacheKey:i.href,url:r.href}}class y{constructor(){this.updatedURLs=[],this.notUpdatedURLs=[],this.handlerWillStart=async({request:t,state:e})=>{e&&(e.originalRequest=t)},this.cachedResponseWillBeUsed=async({event:t,state:e,cachedResponse:s})=>{if("install"===t.type&&e&&e.originalRequest&&e.originalRequest instanceof Request){const t=e.originalRequest.url;s?this.notUpdatedURLs.push(t):this.updatedURLs.push(t)}return s}}}class g{constructor({precacheController:t}){this.cacheKeyWillBeUsed=async({request:t,params:e})=>{const s=(null==e?void 0:e.cacheKey)||this.h.getCacheKeyForURL(t.url);return s?new Request(s,{headers:t.headers}):t},this.h=t}}let R;async function m(t,e){let n=null;if(t.url){n=new URL(t.url).origin}if(n!==self.location.origin)throw new s("cross-origin-copy-response",{origin:n});const i=t.clone(),r={headers:new Headers(i.headers),status:i.status,statusText:i.statusText},o=function(){if(void 0===R){const t=new Response("");if("body"in t)try{new Response(t.body),R=!0}catch(t){R=!1}R=!1}return R}()?i.body:await i.blob();return new Response(o,r)}function v(t,e){const s=new URL(t);for(const t of e)s.searchParams.delete(t);return s.href}class q{constructor(){this.promise=new Promise((t,e)=>{this.resolve=t,this.reject=e})}}const U=new Set;try{self["workbox:strategies:7.4.0"]&&_()}catch(t){}function L(t){return"string"==typeof t?new Request(t):t}class b{constructor(t,e){this.u={},Object.assign(this,e),this.event=e.event,this.l=t,this.p=new q,this.R=[],this.m=[...t.plugins],this.v=new Map;for(const t of this.m)this.v.set(t,{});this.event.waitUntil(this.p.promise)}async fetch(t){const{event:e}=this;let n=L(t);if("navigate"===n.mode&&e instanceof FetchEvent&&e.preloadResponse){const t=await e.preloadResponse;if(t)return t}const i=this.hasCallback("fetchDidFail")?n.clone():null;try{for(const t of this.iterateCallbacks("requestWillFetch"))n=await t({request:n.clone(),event:e})}catch(t){if(t instanceof Error)throw new s("plugin-error-request-will-fetch",{thrownErrorMessage:t.message})}const r=n.clone();try{let t;t=await fetch(n,"navigate"===n.mode?void 0:this.l.fetchOptions);for(const s of this.iterateCallbacks("fetchDidSucceed"))t=await s({event:e,request:r,response:t});return t}catch(t){throw i&&await this.runCallbacks("fetchDidFail",{error:t,event:e,originalRequest:i.clone(),request:r.clone()}),t}}async fetchAndCachePut(t){const e=await this.fetch(t),s=e.clone();return this.waitUntil(this.cachePut(t,s)),e}async cacheMatch(t){const e=L(t);let s;const{cacheName:n,matchOptions:i}=this.l,r=await this.getCacheKey(e,"read"),o=Object.assign(Object.assign({},i),{cacheName:n});s=await caches.match(r,o);for(const t of this.iterateCallbacks("cachedResponseWillBeUsed"))s=await t({cacheName:n,matchOptions:i,cachedResponse:s,request:r,event:this.event})||void 0;return s}async cachePut(t,e){const n=L(t);var i;await(i=0,new Promise(t=>setTimeout(t,i)));const r=await this.getCacheKey(n,"write");if(!e)throw new s("cache-put-with-no-response",{url:(o=r.url,new URL(String(o),location.href).href.replace(new RegExp(`^${location.origin}`),""))});var o;const c=await this.q(e);if(!c)return!1;const{cacheName:a,matchOptions:h}=this.l,u=await self.caches.open(a),l=this.hasCallback("cacheDidUpdate"),f=l?await async function(t,e,s,n){const i=v(e.url,s);if(e.url===i)return t.match(e,n);const r=Object.assign(Object.assign({},n),{ignoreSearch:!0}),o=await t.keys(e,r);for(const e of o)if(i===v(e.url,s))return t.match(e,n)}(u,r.clone(),["__WB_REVISION__"],h):null;try{await u.put(r,l?c.clone():c)}catch(t){if(t instanceof Error)throw"QuotaExceededError"===t.name&&await async function(){for(const t of U)await t()}(),t}for(const t of this.iterateCallbacks("cacheDidUpdate"))await t({cacheName:a,oldResponse:f,newResponse:c.clone(),request:r,event:this.event});return!0}async getCacheKey(t,e){const s=`${t.url} | ${e}`;if(!this.u[s]){let n=t;for(const t of this.iterateCallbacks("cacheKeyWillBeUsed"))n=L(await t({mode:e,request:n,event:this.event,params:this.params}));this.u[s]=n}return this.u[s]}hasCallback(t){for(const e of this.l.plugins)if(t in e)return!0;return!1}async runCallbacks(t,e){for(const s of this.iterateCallbacks(t))await s(e)}*iterateCallbacks(t){for(const e of this.l.plugins)if("function"==typeof e[t]){const s=this.v.get(e),n=n=>{const i=Object.assign(Object.assign({},n),{state:s});return e[t](i)};yield n}}waitUntil(t){return this.R.push(t),t}async doneWaiting(){for(;this.R.length;){const t=this.R.splice(0),e=(await Promise.allSettled(t)).find(t=>"rejected"===t.status);if(e)throw e.reason}}destroy(){this.p.resolve(null)}async q(t){let e=t,s=!1;for(const t of this.iterateCallbacks("cacheWillUpdate"))if(e=await t({request:this.request,response:e,event:this.event})||void 0,s=!0,!e)break;return s||e&&200!==e.status&&(e=void 0),e}}class C{constructor(t={}){this.cacheName=w(t.cacheName),this.plugins=t.plugins||[],this.fetchOptions=t.fetchOptions,this.matchOptions=t.matchOptions}handle(t){const[e]=this.handleAll(t);return e}handleAll(t){t instanceof FetchEvent&&(t={event:t,request:t.request});const e=t.event,s="string"==typeof t.request?new Request(t.request):t.request,n="params"in t?t.params:void 0,i=new b(this,{event:e,request:s,params:n}),r=this.U(i,s,e);return[r,this.L(r,i,s,e)]}async U(t,e,n){let i;await t.runCallbacks("handlerWillStart",{event:n,request:e});try{if(i=await this._(e,t),!i||"error"===i.type)throw new s("no-response",{url:e.url})}catch(s){if(s instanceof Error)for(const r of t.iterateCallbacks("handlerDidError"))if(i=await r({error:s,event:n,request:e}),i)break;if(!i)throw s}for(const s of t.iterateCallbacks("handlerWillRespond"))i=await s({event:n,request:e,response:i});return i}async L(t,e,s,n){let i,r;try{i=await t}catch(r){}try{await e.runCallbacks("handlerDidRespond",{event:n,request:s,response:i}),await e.doneWaiting()}catch(t){t instanceof Error&&(r=t)}if(await e.runCallbacks("handlerDidComplete",{event:n,request:s,response:i,error:r}),e.destroy(),r)throw r}}class E extends C{constructor(t={}){t.cacheName=f(t.cacheName),super(t),this.C=!1!==t.fallbackToNetwork,this.plugins.push(E.copyRedirectedCacheableResponsesPlugin)}async _(t,e){const s=await e.cacheMatch(t);return s||(e.event&&"install"===e.event.type?await this.O(t,e):await this.N(t,e))}async N(t,e){let n;const i=e.params||{};if(!this.C)throw new s("missing-precache-entry",{cacheName:this.cacheName,url:t.url});{const s=i.integrity,r=t.integrity,o=!r||r===s;n=await e.fetch(new Request(t,{integrity:"no-cors"!==t.mode?r||s:void 0})),s&&o&&"no-cors"!==t.mode&&(this.P(),await e.cachePut(t,n.clone()))}return n}async O(t,e){this.P();const n=await e.fetch(t);if(!await e.cachePut(t,n.clone()))throw new s("bad-precaching-response",{url:t.url,status:n.status});return n}P(){let t=null,e=0;for(const[s,n]of this.plugins.entries())n!==E.copyRedirectedCacheableResponsesPlugin&&(n===E.defaultPrecacheCacheabilityPlugin&&(t=s),n.cacheWillUpdate&&e++);0===e?this.plugins.push(E.defaultPrecacheCacheabilityPlugin):e>1&&null!==t&&this.plugins.splice(t,1)}}E.defaultPrecacheCacheabilityPlugin={cacheWillUpdate:async({response:t})=>!t||t.status>=400?null:t},E.copyRedirectedCacheableResponsesPlugin={cacheWillUpdate:async({response:t})=>t.redirected?await m(t):t};class O{constructor({cacheName:t,plugins:e=[],fallbackToNetwork:s=!0}={}){this.j=new Map,this.k=new Map,this.K=new Map,this.l=new E({cacheName:f(t),plugins:[...e,new g({precacheController:this})],fallbackToNetwork:s}),this.install=this.install.bind(this),this.activate=this.activate.bind(this)}get strategy(){return this.l}precache(t){this.addToCacheList(t),this.T||(self.addEventListener("install",this.install),self.addEventListener("activate",this.activate),this.T=!0)}addToCacheList(t){const e=[];for(const n of t){"string"==typeof n?e.push(n):n&&void 0===n.revision&&e.push(n.url);const{cacheKey:t,url:i}=p(n),r="string"!=typeof n&&n.revision?"reload":"default";if(this.j.has(i)&&this.j.get(i)!==t)throw new s("add-to-cache-list-conflicting-entries",{firstEntry:this.j.get(i),secondEntry:t});if("string"!=typeof n&&n.integrity){if(this.K.has(t)&&this.K.get(t)!==n.integrity)throw new s("add-to-cache-list-conflicting-integrities",{url:i});this.K.set(t,n.integrity)}if(this.j.set(i,t),this.k.set(i,r),e.length>0){const t=`Workbox is precaching URLs without revision info: ${e.join(", ")}\nThis is generally NOT safe. Learn more at https://bit.ly/wb-precache`;console.warn(t)}}}install(t){return d(t,async()=>{const e=new y;this.strategy.plugins.push(e);for(const[e,s]of this.j){const n=this.K.get(s),i=this.k.get(e),r=new Request(e,{integrity:n,cache:i,credentials:"same-origin"});await Promise.all(this.strategy.handleAll({params:{cacheKey:s},request:r,event:t}))}const{updatedURLs:s,notUpdatedURLs:n}=e;return{updatedURLs:s,notUpdatedURLs:n}})}activate(t){return d(t,async()=>{const t=await self.caches.open(this.strategy.cacheName),e=await t.keys(),s=new Set(this.j.values()),n=[];for(const i of e)s.has(i.url)||(await t.delete(i),n.push(i.url));return{deletedURLs:n}})}getURLsToCacheKeys(){return this.j}getCachedURLs(){return[...this.j.keys()]}getCacheKeyForURL(t){const e=new URL(t,location.href);return this.j.get(e.href)}getIntegrityForCacheKey(t){return this.K.get(t)}async matchPrecache(t){const e=t instanceof Request?t.url:t,s=this.getCacheKeyForURL(e);if(s){return(await self.caches.open(this.strategy.cacheName)).match(s)}}createHandlerBoundToURL(t){const e=this.getCacheKeyForURL(t);if(!e)throw new s("non-precached-url",{url:t});return s=>(s.request=new Request(t),s.params=Object.assign({cacheKey:e},s.params),this.strategy.handle(s))}}let x;const N=()=>(x||(x=new O),x);class P extends i{constructor(t,e){super(({request:s})=>{const n=t.getURLsToCacheKeys();for(const i of function*(t,{ignoreURLParametersMatching:e=[/^utm_/,/^fbclid$/],directoryIndex:s="index.html",cleanURLs:n=!0,urlManipulation:i}={}){const r=new URL(t,location.href);r.hash="",yield r.href;const o=function(t,e=[]){for(const s of[...t.searchParams.keys()])e.some(t=>t.test(s))&&t.searchParams.delete(s);return t}(r,e);if(yield o.href,s&&o.pathname.endsWith("/")){const t=new URL(o.href);t.pathname+=s,yield t.href}if(n){const t=new URL(o.href);t.pathname+=".html",yield t.href}if(i){const t=i({url:r});for(const e of t)yield e.href}}(s.url,e)){const e=n.get(i);if(e){return{cacheKey:e,integrity:t.getIntegrityForCacheKey(e)}}}},t.strategy)}}t.NavigationRoute=class extends i{constructor(t,{allowlist:e=[/./],denylist:s=[]}={}){super(t=>this.W(t),t),this.M=e,this.S=s}W({url:t,request:e}){if(e&&"navigate"!==e.mode)return!1;const s=t.pathname+t.search;for(const t of this.S)if(t.test(s))return!1;return!!this.M.some(t=>t.test(s))}},t.cleanupOutdatedCaches=function(){self.addEventListener("activate",t=>{const e=f();t.waitUntil((async(t,e="-precache-")=>{const s=(await self.caches.keys()).filter(s=>s.includes(e)&&s.includes(self.registration.scope)&&s!==t);return await Promise.all(s.map(t=>self.caches.delete(t))),s})(e).then(t=>{}))})},t.clientsClaim=function(){self.addEventListener("activate",()=>self.clients.claim())},t.createHandlerBoundToURL=function(t){return N().createHandlerBoundToURL(t)},t.precacheAndRoute=function(t,e){!function(t){N().precache(t)}(t),function(t){const e=N();h(new P(e,t))}(e)},t.registerRoute=h});

package/dist/viewerServer/context.d.ts

@@ -0,0 +1,48 @@
+import type { BoundedAgentContextArtifact } from '../domain/boundedAgentContext.js';
+/**
+ * Reuses the existing Batch 2 bounded manifest-read size limit
+ * (`MAX_MANIFEST_CANDIDATE_BYTES`, 2,000,000 bytes) rather than inventing a
+ * second bound: a `BoundedAgentContextArtifact` is, by its own frozen
+ * contract, already far smaller than that in any realistic case (at most 25
+ * targets, 25 correlation records with at most 5 candidates each, 15
+ * fidelity mismatches, etc. - see `src/domain/boundedAgentContext.ts`'s own
+ * `MAX_*` constants) - the same "generous headroom, never an arbitrarily
+ * large read" rationale applies unchanged.
+ */
+export declare const MAX_CONTEXT_FILE_BYTES = 2000000;
+/**
+ * Session state for the bounded-agent-context the viewer was explicitly
+ * started with. `'none'` when no `--context-file` was supplied at all -
+ * every Batch 1-6 feature remains fully available in this state, and the
+ * viewer never fabricates a context nor infers one from currently-selected
+ * evidence. `'unsupported-version'` is a distinct, honest state for a
+ * recognized-kind context whose `schemaVersion` is not the currently
+ * supported one - never coerced into (or displayed as) the current shape.
+ */
+export type ContextSessionState = {
+    status: 'none';
+} | {
+    status: 'unsupported-version';
+    foundSchemaVersion: string;
+} | {
+    status: 'valid';
+    artifact: BoundedAgentContextArtifact;
+};
+export type ClassifyContextFileResult = {
+    ok: true;
+    state: ContextSessionState;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Classifies one already-parsed JSON value as an explicit `--context-file`
+ * root (task §12: the file *is* one `BoundedAgentContextArtifact` value
+ * directly - no wrapper object). Fails closed (a startup error, per task
+ * §17) on a non-object root, a wrong `artifactKind`, or a current-schema
+ * artifact that is structurally invalid. A recognized kind with a
+ * different, non-current `schemaVersion` is reported as the honest
+ * `'unsupported-version'` state rather than a failure (task §16) - the
+ * caller (`runViewCommand`) still starts the viewer in that case.
+ */
+export declare function classifyContextFileContent(parsed: unknown): ClassifyContextFileResult;

package/dist/viewerServer/context.js

@@ -0,0 +1,60 @@
+/**
+ * v0.8 Batch 7: the narrowest possible viewer-session context-input
+ * boundary. `BoundedAgentContextArtifact` remains programmatic-only in the
+ * current product workflow (no filesystem writer/reader contract exists for
+ * it as an Observer evidence-root artifact family - see
+ * `src/viewerServer/evidence/classify.ts`'s own comment on the "known but
+ * unreadered" kind) - this module does not change that. It only inspects
+ * and validates an explicit, caller-supplied JSON value (the parsed
+ * contents of an operator-supplied `--context-file`) against the existing
+ * canonical `isValidBoundedAgentContextArtifact` - never a second validator,
+ * never a normalization/rewrite of the supplied value, never a call to
+ * `projectBoundedAgentContext` or any correlation-derivation function.
+ *
+ * Byte-reading and JSON parsing remain owned by `src/cli.ts` (mirroring the
+ * existing `loadBindingsFile` boundary exactly); this module receives only
+ * the already-parsed JSON value.
+ */
+import { BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND, BOUNDED_AGENT_CONTEXT_SCHEMA_VERSION, isValidBoundedAgentContextArtifact } from '../domain/boundedAgentContext.js';
+/**
+ * Reuses the existing Batch 2 bounded manifest-read size limit
+ * (`MAX_MANIFEST_CANDIDATE_BYTES`, 2,000,000 bytes) rather than inventing a
+ * second bound: a `BoundedAgentContextArtifact` is, by its own frozen
+ * contract, already far smaller than that in any realistic case (at most 25
+ * targets, 25 correlation records with at most 5 candidates each, 15
+ * fidelity mismatches, etc. - see `src/domain/boundedAgentContext.ts`'s own
+ * `MAX_*` constants) - the same "generous headroom, never an arbitrarily
+ * large read" rationale applies unchanged.
+ */
+export const MAX_CONTEXT_FILE_BYTES = 2_000_000;
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Classifies one already-parsed JSON value as an explicit `--context-file`
+ * root (task §12: the file *is* one `BoundedAgentContextArtifact` value
+ * directly - no wrapper object). Fails closed (a startup error, per task
+ * §17) on a non-object root, a wrong `artifactKind`, or a current-schema
+ * artifact that is structurally invalid. A recognized kind with a
+ * different, non-current `schemaVersion` is reported as the honest
+ * `'unsupported-version'` state rather than a failure (task §16) - the
+ * caller (`runViewCommand`) still starts the viewer in that case.
+ */
+export function classifyContextFileContent(parsed) {
+    if (!isPlainObject(parsed)) {
+        return { ok: false, error: '--context-file root must be a JSON object representing one BoundedAgentContextArtifact value directly (no wrapper object)' };
+    }
+    if (parsed.artifactKind !== BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND) {
+        return { ok: false, error: `--context-file artifactKind must be "${BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND}"; found ${JSON.stringify(parsed.artifactKind)}` };
+    }
+    if (parsed.schemaVersion !== BOUNDED_AGENT_CONTEXT_SCHEMA_VERSION) {
+        const foundSchemaVersion = typeof parsed.schemaVersion === 'string' ? parsed.schemaVersion : 'unknown';
+        return { ok: true, state: { status: 'unsupported-version', foundSchemaVersion } };
+    }
+    const validation = isValidBoundedAgentContextArtifact(parsed);
+    if (!validation.valid) {
+        return { ok: false, error: `--context-file is not a structurally valid current (schemaVersion ${BOUNDED_AGENT_CONTEXT_SCHEMA_VERSION}) bounded-agent-context artifact: ${validation.reason}` };
+    }
+    return { ok: true, state: { status: 'valid', artifact: parsed } };
+}
+//# sourceMappingURL=context.js.map

package/dist/viewerServer/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/viewerServer/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,mCAAmC,EAAE,oCAAoC,EAAE,kCAAkC,EAAE,MAAM,kCAAkC,CAAC;AAGjK;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,SAAS,CAAC;AAkBhD,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAe;IACxD,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,2HAA2H,EAAE,CAAC;IAC3J,CAAC;IACD,IAAI,MAAM,CAAC,YAAY,KAAK,mCAAmC,EAAE,CAAC;QAChE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,wCAAwC,mCAAmC,YAAY,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC;IAC5J,CAAC;IACD,IAAI,MAAM,CAAC,aAAa,KAAK,oCAAoC,EAAE,CAAC;QAClE,MAAM,kBAAkB,GAAG,OAAO,MAAM,CAAC,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QACvG,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,EAAE,CAAC;IACpF,CAAC;IACD,MAAM,UAAU,GAAG,kCAAkC,CAAC,MAAM,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,qEAAqE,oCAAoC,qCAAqC,UAAU,CAAC,MAAM,EAAE,EAAE,CAAC;IACjM,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAgD,EAAE,EAAE,CAAC;AAC9G,CAAC"}

package/dist/viewerServer/evidence/classify.d.ts

@@ -0,0 +1,59 @@
+import type { ObservationArtifact } from '../../domain/schema.js';
+import type { ComparisonArtifact } from '../../domain/comparison.js';
+import type { PersistentBaselineContract, PerChangeContract } from '../../domain/frontendContracts.js';
+import type { FrontendContractEvaluationArtifact } from '../../domain/frontendContractEvaluationArtifact.js';
+import type { ExternalReferenceArtifact } from '../../domain/externalReference.js';
+export type ArtifactFamily = 'observation' | 'comparison' | 'baseline-contract' | 'change-contract' | 'contract-evaluation' | 'external-reference-imported' | 'external-reference-approved';
+/**
+ * Honest, independent viewer-loading/support state - deliberately distinct
+ * from any artifact's own `completion`/evidence-state semantics (see
+ * ClassifiedRecord.artifact for the latter, when the kind carries one).
+ */
+export type ViewerSupportState = 'supported' | 'unsupported-version' | 'invalid-structure' | 'unrecognized-kind' | 'malformed-json' | 'unreadable';
+type FamilyArtifact = {
+    observation: ObservationArtifact;
+    comparison: ComparisonArtifact;
+    'baseline-contract': PersistentBaselineContract;
+    'change-contract': PerChangeContract;
+    'contract-evaluation': FrontendContractEvaluationArtifact;
+    'external-reference-imported': ExternalReferenceArtifact;
+    'external-reference-approved': ExternalReferenceArtifact;
+};
+/** Per-family discriminated union (not a generically-indexed field) so switching on `family` correctly narrows `artifact`'s type. */
+type SupportedRecord = {
+    [K in ArtifactFamily]: {
+        supportState: 'supported';
+        family: K;
+        artifact: FamilyArtifact[K];
+    };
+}[ArtifactFamily];
+export type ClassifiedRecord = SupportedRecord | {
+    supportState: 'unsupported-version';
+    family: ArtifactFamily;
+    foundSchemaVersion: string;
+    supportedSchemaVersion: string;
+} | {
+    supportState: 'invalid-structure';
+    family: ArtifactFamily | undefined;
+    reason: string;
+} | {
+    supportState: 'unrecognized-kind';
+    foundArtifactKind: string | undefined;
+} | {
+    supportState: 'malformed-json';
+    reason: string;
+} | {
+    supportState: 'unreadable';
+    reason: string;
+};
+/**
+ * Classification is not validation (frozen plan §10): this function reads
+ * bounded manifest bytes, parses JSON, and peeks only `artifactKind`/
+ * `schemaVersion` to decide *which* existing canonical reader to try - the
+ * canonical reader's own structural validator remains the sole authority on
+ * whether a candidate is actually a valid instance of that family. This
+ * function never accepts a candidate that its dispatched reader rejects, and
+ * never invents a result the reader did not itself produce.
+ */
+export declare function classifyManifest(manifestPath: string): Promise<ClassifiedRecord>;
+export {};

package/dist/viewerServer/evidence/classify.js

@@ -0,0 +1,124 @@
+import { readFile, stat } from 'node:fs/promises';
+import { ARTIFACT_KIND, SCHEMA_VERSION } from '../../domain/schema.js';
+import { readObservationArtifact } from '../../artifacts/artifactReader.js';
+import { COMPARISON_ARTIFACT_KIND, COMPARISON_SCHEMA_VERSION } from '../../domain/comparison.js';
+import { readComparisonArtifact } from '../../artifacts/comparisonArtifactReader.js';
+import { CONTRACT_ARTIFACT_KIND, CONTRACT_SCHEMA_VERSION } from '../../domain/frontendContracts.js';
+import { readPersistentBaselineContract, readPerChangeContract } from '../../artifacts/frontendContractArtifactReader.js';
+import { EVALUATION_ARTIFACT_KIND, EVALUATION_SCHEMA_VERSION } from '../../domain/frontendContractEvaluationArtifact.js';
+import { readFrontendContractEvaluationArtifact } from '../../artifacts/frontendContractEvaluationArtifactReader.js';
+import { EXTERNAL_REFERENCE_ARTIFACT_KIND, EXTERNAL_REFERENCE_SCHEMA_VERSION } from '../../domain/externalReference.js';
+import { readExternalReferenceArtifact } from '../../artifacts/externalReferenceArtifactReader.js';
+import { MAX_MANIFEST_CANDIDATE_BYTES } from './limits.js';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Classification is not validation (frozen plan §10): this function reads
+ * bounded manifest bytes, parses JSON, and peeks only `artifactKind`/
+ * `schemaVersion` to decide *which* existing canonical reader to try - the
+ * canonical reader's own structural validator remains the sole authority on
+ * whether a candidate is actually a valid instance of that family. This
+ * function never accepts a candidate that its dispatched reader rejects, and
+ * never invents a result the reader did not itself produce.
+ */
+export async function classifyManifest(manifestPath) {
+    let size;
+    try {
+        size = (await stat(manifestPath)).size;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { supportState: 'unreadable', reason: `could not stat candidate manifest: ${message}` };
+    }
+    if (size > MAX_MANIFEST_CANDIDATE_BYTES) {
+        return { supportState: 'unreadable', reason: `candidate manifest exceeds the bounded size limit (${MAX_MANIFEST_CANDIDATE_BYTES} bytes)` };
+    }
+    let raw;
+    try {
+        raw = await readFile(manifestPath, 'utf8');
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { supportState: 'unreadable', reason: `could not read candidate manifest: ${message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { supportState: 'malformed-json', reason: message };
+    }
+    if (!isPlainObject(parsed)) {
+        return { supportState: 'unrecognized-kind', foundArtifactKind: undefined };
+    }
+    const kind = typeof parsed.artifactKind === 'string' ? parsed.artifactKind : undefined;
+    const version = typeof parsed.schemaVersion === 'string' ? parsed.schemaVersion : undefined;
+    switch (kind) {
+        case ARTIFACT_KIND: {
+            if (version !== SCHEMA_VERSION) {
+                return { supportState: 'unsupported-version', family: 'observation', foundSchemaVersion: version ?? 'unknown', supportedSchemaVersion: SCHEMA_VERSION };
+            }
+            const read = await readObservationArtifact(manifestPath);
+            if (!read.ok)
+                return { supportState: 'invalid-structure', family: 'observation', reason: read.reason };
+            return { supportState: 'supported', family: 'observation', artifact: read.artifact };
+        }
+        case COMPARISON_ARTIFACT_KIND: {
+            if (version !== COMPARISON_SCHEMA_VERSION) {
+                return { supportState: 'unsupported-version', family: 'comparison', foundSchemaVersion: version ?? 'unknown', supportedSchemaVersion: COMPARISON_SCHEMA_VERSION };
+            }
+            const read = await readComparisonArtifact(manifestPath);
+            if (!read.ok)
+                return { supportState: 'invalid-structure', family: 'comparison', reason: read.reason };
+            return { supportState: 'supported', family: 'comparison', artifact: read.artifact };
+        }
+        case CONTRACT_ARTIFACT_KIND: {
+            if (version !== CONTRACT_SCHEMA_VERSION) {
+                return { supportState: 'unsupported-version', family: 'baseline-contract', foundSchemaVersion: version ?? 'unknown', supportedSchemaVersion: CONTRACT_SCHEMA_VERSION };
+            }
+            // Two structurally distinct persisted shapes share one artifactKind/schemaVersion (contractClass discriminates) -
+            // the canonical validators, not this classifier, decide which one (if either) a candidate actually is.
+            const baseline = await readPersistentBaselineContract(manifestPath);
+            if (baseline.ok)
+                return { supportState: 'supported', family: 'baseline-contract', artifact: baseline.contract };
+            const change = await readPerChangeContract(manifestPath);
+            if (change.ok)
+                return { supportState: 'supported', family: 'change-contract', artifact: change.contract };
+            return { supportState: 'invalid-structure', family: undefined, reason: `matches neither baseline nor per-change contract shape (baseline: ${baseline.reason}; change: ${change.reason})` };
+        }
+        case EVALUATION_ARTIFACT_KIND: {
+            if (version !== EVALUATION_SCHEMA_VERSION) {
+                return { supportState: 'unsupported-version', family: 'contract-evaluation', foundSchemaVersion: version ?? 'unknown', supportedSchemaVersion: EVALUATION_SCHEMA_VERSION };
+            }
+            const read = await readFrontendContractEvaluationArtifact(manifestPath);
+            if (!read.ok)
+                return { supportState: 'invalid-structure', family: 'contract-evaluation', reason: read.reason };
+            return { supportState: 'supported', family: 'contract-evaluation', artifact: read.artifact };
+        }
+        case EXTERNAL_REFERENCE_ARTIFACT_KIND: {
+            if (version !== EXTERNAL_REFERENCE_SCHEMA_VERSION) {
+                return {
+                    supportState: 'unsupported-version',
+                    family: 'external-reference-imported',
+                    foundSchemaVersion: version ?? 'unknown',
+                    supportedSchemaVersion: EXTERNAL_REFERENCE_SCHEMA_VERSION,
+                };
+            }
+            const read = await readExternalReferenceArtifact(manifestPath);
+            if (!read.ok)
+                return { supportState: 'invalid-structure', family: undefined, reason: read.reason };
+            const family = read.artifact.lifecycle.state === 'approved' ? 'external-reference-approved' : 'external-reference-imported';
+            return { supportState: 'supported', family, artifact: read.artifact };
+        }
+        default:
+            // Includes both a genuinely unknown string and the known-but-unreadered
+            // `my-frontend-observer/bounded-agent-context` kind (see frozen plan
+            // §8: no disk reader/writer exists for that family - inventing
+            // persistence-shaped handling for it here would fabricate support that
+            // does not exist).
+            return { supportState: 'unrecognized-kind', foundArtifactKind: kind };
+    }
+}
+//# sourceMappingURL=classify.js.map

package/dist/viewerServer/evidence/classify.js.map

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

package/dist/viewerServer/evidence/comparisonView.d.ts

@@ -0,0 +1,28 @@
+import type { LinkStatus } from './linkedEvidence.js';
+export type ComparisonViewResult = {
+    ok: true;
+    before: LinkStatus;
+    after: LinkStatus;
+} | {
+    ok: false;
+    reason: 'unknown-handle';
+} | {
+    ok: false;
+    reason: 'not-a-comparison';
+} | {
+    ok: false;
+    reason: 'not-currently-loadable';
+};
+/**
+ * Batch 4's one additive server-side computation for comparisons: resolves
+ * the persisted `ComparisonArtifact`'s `before`/`after` source-observation
+ * references (exact identity only, `linkedEvidence.ts`) against the current
+ * evidence root. Never calls `compareObservations` - the persisted
+ * `ComparisonArtifact` (differences, relationshipsBefore/After,
+ * comparability, etc.) remains authoritative and is fetched unchanged
+ * through the existing Batch 2 `GET /api/artifacts/<handle>`; this endpoint
+ * only answers "where are its source observations, if anywhere in this
+ * root". Same handle-decode -> contained-dir-resolve -> re-classify
+ * discipline as `observationView.ts`/`mediaResolver.ts`.
+ */
+export declare function getComparisonView(root: string, handle: string): Promise<ComparisonViewResult>;

package/dist/viewerServer/evidence/comparisonView.js

@@ -0,0 +1,43 @@
+import { join } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { classifyManifest } from './classify.js';
+import { decodeArtifactHandle } from './handles.js';
+import { resolveContainedDir } from './pathSafety.js';
+import { resolveObservationByReference } from './linkedEvidence.js';
+/**
+ * Batch 4's one additive server-side computation for comparisons: resolves
+ * the persisted `ComparisonArtifact`'s `before`/`after` source-observation
+ * references (exact identity only, `linkedEvidence.ts`) against the current
+ * evidence root. Never calls `compareObservations` - the persisted
+ * `ComparisonArtifact` (differences, relationshipsBefore/After,
+ * comparability, etc.) remains authoritative and is fetched unchanged
+ * through the existing Batch 2 `GET /api/artifacts/<handle>`; this endpoint
+ * only answers "where are its source observations, if anywhere in this
+ * root". Same handle-decode -> contained-dir-resolve -> re-classify
+ * discipline as `observationView.ts`/`mediaResolver.ts`.
+ */
+export async function getComparisonView(root, handle) {
+    const decoded = decodeArtifactHandle(handle);
+    if (!decoded.ok)
+        return { ok: false, reason: 'unknown-handle' };
+    const dir = resolveContainedDir(root, decoded.relativeDir);
+    if (dir === undefined)
+        return { ok: false, reason: 'unknown-handle' };
+    try {
+        const dirInfo = await stat(dir);
+        if (!dirInfo.isDirectory())
+            return { ok: false, reason: 'unknown-handle' };
+    }
+    catch {
+        return { ok: false, reason: 'unknown-handle' };
+    }
+    const classified = await classifyManifest(join(dir, 'manifest.json'));
+    if (classified.supportState !== 'supported')
+        return { ok: false, reason: 'not-currently-loadable' };
+    if (classified.family !== 'comparison')
+        return { ok: false, reason: 'not-a-comparison' };
+    const { artifact } = classified;
+    const [before, after] = await Promise.all([resolveObservationByReference(root, artifact.before), resolveObservationByReference(root, artifact.after)]);
+    return { ok: true, before, after };
+}
+//# sourceMappingURL=comparisonView.js.map

package/dist/viewerServer/evidence/comparisonView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comparisonView.js","sourceRoot":"","sources":["../../../src/viewerServer/evidence/comparisonView.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AASpE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,MAAc;IAClE,MAAM,OAAO,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAEhE,MAAM,GAAG,GAAG,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC3D,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAEtE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC7E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACjD,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC,CAAC;IACtE,IAAI,UAAU,CAAC,YAAY,KAAK,WAAW;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IACpG,IAAI,UAAU,CAAC,MAAM,KAAK,YAAY;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAEzF,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC;IAChC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,6BAA6B,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,6BAA6B,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEvJ,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AACrC,CAAC"}

package/dist/viewerServer/evidence/contextSourceView.d.ts

@@ -0,0 +1,25 @@
+/**
+ * v0.8 Batch 7: resolves a validated `BoundedAgentContextArtifact.sources`
+ * block against the current evidence root by exact canonical identity only
+ * (never pathname/name/similarity heuristics), reusing `linkedEvidence.ts`'s
+ * established resolver pattern (Batch 4/5) - every lookup here is a bounded
+ * discovery walk that matches on the exact identity fields the source
+ * reference actually carries. Never calls `compareObservations`,
+ * `evaluateFrontendContract`, `projectBoundedAgentContext`, or any
+ * correlation-derivation function.
+ */
+import type { BoundedAgentContextSourceReferences } from '../../domain/boundedAgentContext.js';
+import type { LinkStatus } from './linkedEvidence.js';
+export interface ContextSourceResolution {
+    /** One resolution per `sources.observationIds` entry, in the same order. */
+    observations: {
+        observationId: string;
+        link: LinkStatus;
+    }[];
+    comparison?: LinkStatus;
+    baselineContract?: LinkStatus;
+    changeContract?: LinkStatus;
+    evaluation?: LinkStatus;
+    reference?: LinkStatus;
+}
+export declare function resolveContextSources(root: string, sources: BoundedAgentContextSourceReferences): Promise<ContextSourceResolution>;

package/dist/viewerServer/evidence/contextSourceView.js

@@ -0,0 +1,20 @@
+import { resolveObservationById, resolveComparisonByIdentity, resolveBaselineContractById, resolveChangeContractById, resolveEvaluationByIdentity, resolveReferenceByIdentity } from './linkedEvidence.js';
+export async function resolveContextSources(root, sources) {
+    const [observationLinks, comparison, baselineContract, changeContract, evaluation, reference] = await Promise.all([
+        Promise.all(sources.observationIds.map(async (observationId) => ({ observationId, link: await resolveObservationById(root, observationId) }))),
+        sources.comparisonId !== undefined && sources.comparisonRequestId !== undefined ? resolveComparisonByIdentity(root, sources.comparisonId, sources.comparisonRequestId) : Promise.resolve(undefined),
+        sources.baselineContractId !== undefined ? resolveBaselineContractById(root, sources.baselineContractId) : Promise.resolve(undefined),
+        sources.changeContractId !== undefined ? resolveChangeContractById(root, sources.changeContractId) : Promise.resolve(undefined),
+        sources.evaluationId !== undefined && sources.evaluationRequestId !== undefined ? resolveEvaluationByIdentity(root, sources.evaluationId, sources.evaluationRequestId) : Promise.resolve(undefined),
+        sources.referenceId !== undefined && sources.referenceRequestId !== undefined ? resolveReferenceByIdentity(root, sources.referenceId, sources.referenceRequestId) : Promise.resolve(undefined),
+    ]);
+    return {
+        observations: observationLinks,
+        ...(comparison !== undefined ? { comparison } : {}),
+        ...(baselineContract !== undefined ? { baselineContract } : {}),
+        ...(changeContract !== undefined ? { changeContract } : {}),
+        ...(evaluation !== undefined ? { evaluation } : {}),
+        ...(reference !== undefined ? { reference } : {}),
+    };
+}
+//# sourceMappingURL=contextSourceView.js.map

package/dist/viewerServer/evidence/contextSourceView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextSourceView.js","sourceRoot":"","sources":["../../../src/viewerServer/evidence/contextSourceView.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AAY3M,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAY,EAAE,OAA4C;IACpG,MAAM,CAAC,gBAAgB,EAAE,UAAU,EAAE,gBAAgB,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAChH,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC,IAAI,EAAE,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9I,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,OAAO,CAAC,mBAAmB,KAAK,SAAS,CAAC,CAAC,CAAC,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;QACnM,OAAO,CAAC,kBAAkB,KAAK,SAAS,CAAC,CAAC,CAAC,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;QACrI,OAAO,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,yBAAyB,CAAC,IAAI,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;QAC/H,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,OAAO,CAAC,mBAAmB,KAAK,SAAS,CAAC,CAAC,CAAC,2BAA2B,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;QACnM,OAAO,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,CAAC,kBAAkB,KAAK,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC,IAAI,EAAE,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;KAC/L,CAAC,CAAC;IAEH,OAAO;QACL,YAAY,EAAE,gBAAgB;QAC9B,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3D,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClD,CAAC;AACJ,CAAC"}

package/dist/viewerServer/evidence/discovery.d.ts

@@ -0,0 +1,31 @@
+export interface DiscoveredManifest {
+    /** Absolute path to the candidate `manifest.json` file. */
+    absolutePath: string;
+    /** Absolute path to its containing directory (the artifact's own root). */
+    absoluteDir: string;
+    /** Root-relative, forward-slash-normalized directory path - display/handle material only, never trusted for filesystem access without re-resolution+containment-check. */
+    relativeDir: string;
+}
+export interface DiscoveryResult {
+    manifests: DiscoveredManifest[];
+    /** True if MAX_MANIFEST_CANDIDATES, MAX_DIRECTORIES_VISITED, or MAX_DISCOVERY_DEPTH was hit before the walk completed naturally. */
+    truncated: boolean;
+}
+/**
+ * Bounded, deterministic, symlink-safe walk beneath `root` looking only for
+ * files literally named `manifest.json` (the one filename every current
+ * persisted artifact family uses - see src/artifacts/*Writer.ts). No other
+ * filename is ever opened or classified, so arbitrary files
+ * (`package.json`, `.env`, source files, unrelated JSON) can never become
+ * evidence merely by existing under the root.
+ *
+ * Security properties:
+ * - directory entries that are symbolic links or reparse points/junctions
+ *   (`dirent.isSymbolicLink()`) are never followed, so discovery can never
+ *   leave the resolved root via a symlink;
+ * - traversal depth, directories visited, and candidate manifests found are
+ *   all independently bounded (see limits.ts) - discovery always terminates
+ *   and never depends on filesystem enumeration order for its *result set*
+ *   (see the caller-side deterministic sort in index.ts).
+ */
+export declare function discoverManifests(root: string): Promise<DiscoveryResult>;

package/dist/viewerServer/evidence/discovery.js

@@ -0,0 +1,78 @@
+import { readdir } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { MAX_DIRECTORIES_VISITED, MAX_DISCOVERY_DEPTH, MAX_MANIFEST_CANDIDATES } from './limits.js';
+function toPosixRelative(root, absoluteDir) {
+    const rel = relative(root, absoluteDir);
+    return rel === '' ? '.' : rel.split(sep).join('/');
+}
+/**
+ * Bounded, deterministic, symlink-safe walk beneath `root` looking only for
+ * files literally named `manifest.json` (the one filename every current
+ * persisted artifact family uses - see src/artifacts/*Writer.ts). No other
+ * filename is ever opened or classified, so arbitrary files
+ * (`package.json`, `.env`, source files, unrelated JSON) can never become
+ * evidence merely by existing under the root.
+ *
+ * Security properties:
+ * - directory entries that are symbolic links or reparse points/junctions
+ *   (`dirent.isSymbolicLink()`) are never followed, so discovery can never
+ *   leave the resolved root via a symlink;
+ * - traversal depth, directories visited, and candidate manifests found are
+ *   all independently bounded (see limits.ts) - discovery always terminates
+ *   and never depends on filesystem enumeration order for its *result set*
+ *   (see the caller-side deterministic sort in index.ts).
+ */
+export async function discoverManifests(root) {
+    const manifests = [];
+    let directoriesVisited = 0;
+    let truncated = false;
+    async function walk(dir, depth) {
+        if (truncated)
+            return;
+        if (depth > MAX_DISCOVERY_DEPTH) {
+            truncated = true;
+            return;
+        }
+        if (directoriesVisited >= MAX_DIRECTORIES_VISITED) {
+            truncated = true;
+            return;
+        }
+        directoriesVisited += 1;
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            // Unreadable directory (permissions, race with external deletion): skip silently, not a discovery failure.
+            return;
+        }
+        // Deterministic child ordering regardless of filesystem enumeration order.
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            if (truncated)
+                return;
+            if (entry.isSymbolicLink())
+                continue; // never follow symlinks/junctions/reparse points, for files or directories
+            if (entry.isDirectory()) {
+                await walk(join(dir, entry.name), depth + 1);
+                continue;
+            }
+            if (entry.isFile() && entry.name === 'manifest.json') {
+                if (manifests.length >= MAX_MANIFEST_CANDIDATES) {
+                    truncated = true;
+                    return;
+                }
+                manifests.push({
+                    absolutePath: join(dir, entry.name),
+                    absoluteDir: dir,
+                    relativeDir: toPosixRelative(root, dir),
+                });
+            }
+        }
+    }
+    await walk(root, 0);
+    // Final deterministic ordering of the result set itself, independent of traversal order.
+    manifests.sort((a, b) => (a.relativeDir < b.relativeDir ? -1 : a.relativeDir > b.relativeDir ? 1 : 0));
+    return { manifests, truncated };
+}
+//# sourceMappingURL=discovery.js.map