graphlin 0.1.3 → 0.2.1

package/runtime/web/extension-frame.js

@@ -0,0 +1,128 @@
+import { validateScene } from '../extensions/scene.mjs';
+import { jsonBytes, id, integer, EXTENSION_LIMITS } from '../extensions/contracts.mjs';
+import { validateMessage } from '../extensions/sdk.mjs';
+
+const CONTEXT = ['instanceId', 'projectId', 'revision', 'viewEpoch', 'requestId'];
+const nonceValue = () => {
+  const bytes = new Uint8Array(24);
+  globalThis.crypto.getRandomValues(bytes);
+  return [...bytes].map(value => value.toString(16).padStart(2, '0')).join('');
+};
+
+/** Only the host's projected-data route supplies `model`. A frame never receives
+ * fetch, cookies, a daemon token, or the host's unprojected snapshot.
+ */
+export function createExtensionFrame({
+  root, extension, onSelect = () => {}, onFailure = () => {},
+  Channel = globalThis.MessageChannel, nonce = nonceValue(), timeout = 5000,
+}) {
+  const frame = root.ownerDocument.createElement('iframe');
+  frame.setAttribute('sandbox', 'allow-scripts');
+  frame.setAttribute('referrerpolicy', 'no-referrer');
+  frame.setAttribute('title', extension.manifest.name || extension.id);
+  frame.setAttribute('src', `/api/extensions/frame/${encodeURIComponent(extension.id)}?nonce=${encodeURIComponent(nonce)}`);
+  const channel = new Channel(), port = channel.port1;
+  let stopped = false, loaded = false, ready = false, requestNumber = 0, pending, latest;
+  const granted = model => extension.grant?.approved === true &&
+    extension.grant.projectId === model?.projectId && extension.grant.extensionId === extension.id &&
+    extension.grant.digest === extension.digest;
+  let readyResolve, readyReject;
+  const readyPromise = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+  // A frame can fail before update attaches its await handler.
+  readyPromise.catch(() => {});
+  const readyTimer = setTimeout(() => fail(new Error('extension_ready_timeout')), timeout);
+  function rejectPending(error) {
+    if (pending) { clearTimeout(pending.timer); pending.reject(error); pending = null; }
+  }
+  function stop(error = new Error('extension_disposed')) {
+    if (stopped) return;
+    stopped = true;
+    clearTimeout(readyTimer);
+    readyReject(error); rejectPending(error);
+    port.onmessage = null; port.close(); channel.port2.close();
+    frame.removeEventListener('load', onLoad); frame.remove();
+    latest = null;
+  }
+  function fail(error) { stop(error); onFailure(); }
+  function onLoad() {
+    if (stopped) return;
+    if (loaded) { fail(new Error('extension_navigated')); return; }
+    loaded = true;
+    // Opaque-origin sandbox recipients require "*"; the exact frame WindowProxy,
+    // a fresh nonce, and the one-use port bind this bootstrap to its document.
+    frame.contentWindow.postMessage({ type: 'graphlin:bootstrap', apiVersion: 1, nonce }, '*', [channel.port2]);
+  }
+  let windowStart = Date.now(), messages = 0;
+  port.onmessage = event => {
+    if (stopped) return;
+    try {
+      if (Date.now() - windowStart > 1000) { windowStart = Date.now(); messages = 0; }
+      if (++messages > 120) throw new Error('extension_message_rate');
+      const message = event.data;
+      jsonBytes(message, EXTENSION_LIMITS.projectionBytes, 'extension_message_limit');
+      if (!ready) {
+        if (!loaded || message?.type !== 'graphlin:ready' || message.apiVersion !== 1 || message.nonce !== nonce)
+          throw new Error('invalid_extension_ready');
+        ready = true; clearTimeout(readyTimer); readyResolve(); return;
+      }
+      if (!message || message.apiVersion !== 1 || !latest ||
+        !CONTEXT.every(key => message[key] === latest.context[key])) return;
+      validateMessage(message, { model: latest.model, context: { apiVersion: 1, ...latest.context } });
+      if (message.type === 'graphlin:select') {
+        const capabilities = extension.manifest.capabilities || [];
+        const field = message.selection?.entityId ? 'entities' : message.selection?.relationId ? 'relations' : 'activity';
+        if (!granted(latest.model) || !capabilities.some(value => ['selection.request', 'inspection.request'].includes(value)) ||
+          !extension.grant.fields?.includes(field) || (field === 'relations' && !extension.grant.fields.includes('entities'))) return;
+        const selection = message.selection;
+        if (selection?.entityId && latest.model.entities.some(entity => entity.id === selection.entityId))
+          onSelect({ entityId: selection.entityId });
+        else if (selection?.relationId && latest.model.relations.some(relation => relation.id === selection.relationId))
+          onSelect({ relationId: selection.relationId });
+        else if (selection?.activityId && latest.model.activity.some(activity => activity.id === selection.activityId))
+          onSelect({ activityId: selection.activityId });
+        return;
+      }
+      if (!pending) return;
+      if (message.type === 'graphlin:status' && message.status === 'busy') return;
+      if (message.type === 'graphlin:status' && message.status === 'error') {
+        rejectPending(new Error('extension_projection_failed')); return;
+      }
+      let result;
+      if (message.type === 'graphlin:scene' && extension.manifest.renderer.kind === 'graphlin-scene')
+        result = { kind: 'scene', scene: validateScene(message.scene, { model: latest.model }) };
+      else if (message.type === 'graphlin:status' && extension.manifest.renderer.kind === 'custom' &&
+        ['ready', 'empty'].includes(message.status) && integer(message.itemCount, 20000))
+        result = { kind: 'custom', status: message.status, itemCount: message.itemCount };
+      else if (message.type === 'graphlin:error') { rejectPending(new Error('extension_projection_failed')); return; }
+      else throw new Error('invalid_extension_response');
+      clearTimeout(pending.timer); const resolve = pending.resolve; pending = null; resolve(result);
+    } catch (error) { fail(error); }
+  };
+  port.start();
+  frame.addEventListener('load', onLoad);
+  root.replaceChildren(frame);
+  return {
+    async update({ model, settings = {}, selection = null, viewEpoch = 0 }) {
+      if (!granted(model)) throw new Error('extension_grant_denied');
+      await readyPromise;
+      if (stopped) throw new Error('extension_disposed');
+      rejectPending(new Error('extension_superseded'));
+      const context = {
+        instanceId: `frame.${nonce}`, projectId: model.projectId, revision: model.revision,
+        viewEpoch, requestId: `request.${++requestNumber}`,
+      };
+      if (!id(context.projectId) || !integer(context.revision)) throw new Error('invalid_extension_context');
+      const message = { type: 'graphlin:project', apiVersion: 1, ...context, model, settings, selection };
+      jsonBytes(message, EXTENSION_LIMITS.projectionBytes);
+      latest = { context, model };
+      return new Promise((resolve, reject) => {
+        pending = { resolve, reject, timer: setTimeout(() => fail(new Error('extension_projection_timeout')), timeout) };
+        port.postMessage(message);
+      });
+    },
+    dispose() {
+      if (!stopped && ready && latest) port.postMessage({ type: 'graphlin:dispose', apiVersion: 1, ...latest.context });
+      stop();
+    },
+  };
+}

package/runtime/web/index.html

@@ -6,8 +6,9 @@
   <meta name="color-scheme" content="light">
   <meta name="darkreader-lock">
   <meta name="referrer" content="no-referrer">
-  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; font-src 'self'; base-uri 'none'; form-action 'none'; object-src 'none'">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; frame-src 'self'; img-src 'self' data:; font-src 'self'; base-uri 'none'; form-action 'none'; object-src 'none'">
   <title>Graphlin — Live architecture</title>
+  <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg' viewBox='0 0 32 32'%3E%3Crect x='4' y='3' width='20' height='24' rx='4' fill='white' stroke='%233d60bc' stroke-width='2'/%3E%3Crect x='18' y='18' width='11' height='11' rx='3' fill='%23399783'/%3E%3C/svg%3E">
   <link rel="stylesheet" href="/style.css">
   <script type="module" src="/app.js"></script>
 </head>
@@ -44,6 +45,10 @@
 
       <section class="workspace" aria-label="Session workspace">
         <div class="workspace-toolbar">
+          <label class="session-picker" for="visualizer">
+            <span>View</span>
+            <select id="visualizer" aria-label="Visualizer"><option value="graphlin.code">Code</option></select>
+          </label>
           <label class="session-picker" for="session">
             <span>Session</span>
             <select id="session" disabled><option value="">Waiting for a session</option></select>
@@ -120,6 +125,35 @@
                 <div id="node-type-filters" role="group" aria-label="Visible component types"></div>
               </div>
             </div>
+            <div class="view-context" id="view-context" hidden>
+              <nav id="scope-breadcrumbs" aria-label="Source scope"></nav>
+              <label id="c4-level-label" hidden>Level <select id="c4-level">
+                <option value="context">Context</option><option value="applications" selected>Applications / datastores</option>
+                <option value="components">Components</option><option value="code">Code</option>
+              </select></label>
+              <button id="architecture-discover" type="button" aria-describedby="architecture-status" hidden>Discover architecture</button>
+              <label id="baseline-label" hidden>Baseline <select id="task-baseline"><option value="">Choose checkpoint</option></select></label>
+              <button id="baseline-create" type="button" hidden>Set baseline now</button>
+              <label>Position <select id="model-position"><option value="">Live</option></select></label>
+              <label class="follow-control"><input id="follow-agent" type="checkbox" checked> Follow agent</label>
+              <button id="view-retry" type="button" hidden>Retry view</button>
+              <div id="analysis-controls" hidden>
+                <label>Analysis <select id="analysis-profile" aria-describedby="analysis-note"></select></label>
+                <button id="analysis-run" type="button" aria-describedby="analysis-note">Run analysis</button>
+                <button id="analysis-access" type="button">Manage access</button>
+              </div>
+            </div>
+            <p id="architecture-status" class="architecture-status" role="status" aria-live="polite" hidden></p>
+            <p class="view-status" id="view-status" role="status" hidden></p>
+            <section class="extension-access" id="extension-access" aria-label="Visualizer data access" hidden>
+              <p id="extension-access-description"></p>
+              <div id="extension-fields"></div>
+              <label><input type="checkbox" id="extension-history"> Allow retained history</label>
+              <div id="extension-profiles"></div>
+              <p id="analysis-note" hidden>Running an approved profile can send locally filtered source evidence to the configured classification service. This project must already allow source transmission. Approving a visualizer does not enable source transmission. Analysis runs only when you choose Run analysis, using the selected entity or up to 256 entities in the current scope.</p>
+              <button id="extension-approve" type="button">Allow selected data</button>
+              <button id="extension-deny" type="button">Deny access</button>
+            </section>
             <div class="diagram-stage" id="diagram-stage">
               <svg id="architecture" viewBox="0 0 920 510" role="group" tabindex="0" aria-labelledby="diagram-title diagram-desc">
                 <title id="diagram-title">Architecture diagram</title>
@@ -129,11 +163,13 @@
                   <marker id="arrow-proposed" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M 0 0 L 10 5 L 0 10 Z" class="arrow-proposed"></path></marker>
                   <marker id="arrow-stale" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto"><path d="M 0 0 L 10 5 L 0 10 Z" class="arrow-stale"></path></marker>
                 </defs>
+                <g id="group-layer"></g>
                 <g id="edge-layer"></g>
                 <g id="edge-label-layer"></g>
                 <g id="node-layer"></g>
                 <g id="effects-layer" aria-hidden="true" pointer-events="none"></g>
               </svg>
+              <section id="custom-view" class="custom-view" aria-label="Custom visualizer" hidden></section>
               <div class="empty-canvas" id="empty-canvas">
                 <div class="empty-map" aria-hidden="true"><i></i><span></span><i></i></div>
                 <h3 id="empty-title">Your architecture starts here.</h3>
@@ -154,6 +190,7 @@
               </div>
               <span id="graph-count">No components yet</span>
             </div>
+            <p class="view-coverage" id="view-coverage" role="status" hidden></p>
             <p class="diagram-note" id="diagram-note">Code classification does not establish runtime connectivity.</p>
           </section>
 

package/runtime/web/model-client.js

@@ -0,0 +1,162 @@
+import { id, integer, jsonBytes } from '../extensions/contracts.mjs';
+
+const COLLECTIONS = ['entities', 'relations', 'interpretations', 'activity', 'sessions', 'checkpoints'];
+export const VIEW_MODEL_LIMITS = Object.freeze({
+  entities: 2048, relations: 4096, interpretations: 512, activity: 2048, sessions: 100, checkpoints: 100,
+});
+const stalePage = () => Object.assign(new Error('inconsistent_model_page'), { status: 409 });
+
+export function readModel(value) {
+  if (value?.schemaVersion !== 2 || !id(value.projectId) ||
+    !integer(value.revision) || !integer(value.sequence)) throw new Error('invalid_model');
+  for (const [key, max] of Object.entries({
+    entities: 20000, relations: 40000, interpretations: 512, activity: 2048, sessions: 100, checkpoints: 100,
+  })) if (!Array.isArray(value[key]) || value[key].length > max) throw new Error('invalid_model');
+  jsonBytes(value, 8 * 1024 * 1024);
+  for (const entity of value.entities) if (!id(entity.id) || typeof entity.label !== 'string' ||
+    !Array.isArray(entity.sourceRefs)) throw new Error('invalid_model_entity');
+  if (new Set(value.entities.map(entity => entity.id)).size !== value.entities.length) throw new Error('duplicate_model_entity');
+  if (value.transport && (typeof value.transport.epoch !== 'string' ||
+    !integer(value.transport.sequence) || typeof value.transport.eventId !== 'string')) throw new Error('invalid_model_transport');
+  return value;
+}
+
+export function modelQuery(selection = {}) {
+  const params = new URLSearchParams();
+  for (const key of ['scope', 'session', 'checkpoint']) if (selection[key]) params.set(key, selection[key]);
+  return params.size ? `?${params}` : '';
+}
+
+/** Hydrates one scope, not an unlimited project index. Every cursor is bound by
+ * the server to the same revision, model sequence, policy fingerprint and epoch.
+ */
+export async function hydrateModel(raw, { request, selection = {}, signal,
+  limits = VIEW_MODEL_LIMITS, maxBytes = 6 * 1024 * 1024, fetchPages = true } = {}) {
+  readModel(raw);
+  const result = { ...raw, coverage: { ...raw.coverage }, pages: { ...raw.pages } };
+  let usedBytes = new TextEncoder().encode(JSON.stringify(raw)).length;
+  let incomplete = false;
+  const totals = {}, retained = {};
+  for (const kind of COLLECTIONS) {
+    const pageInfo = raw.pages?.[kind];
+    if (pageInfo && (!integer(pageInfo.total) || pageInfo.total < raw[kind].length ||
+      pageInfo.returned !== raw[kind].length)) throw new Error('invalid_model_pages');
+    const values = raw[kind].slice(0, limits[kind]), seenIds = new Set(values.map(value => value.id));
+    if (seenIds.size !== values.length) throw new Error('duplicate_model_record');
+    totals[kind] = raw.pages?.[kind]?.total ?? raw[kind].length;
+    let cursor = raw.pages?.[kind]?.nextCursor;
+    const seenCursors = new Set();
+    while (fetchPages && cursor && values.length < limits[kind] && usedBytes < maxBytes) {
+      if (typeof cursor !== 'string' || cursor.length > 2048 || seenCursors.has(cursor)) throw new Error('invalid_model_cursor');
+      seenCursors.add(cursor);
+      const params = new URLSearchParams(modelQuery(selection).slice(1));
+      params.set('cursor', cursor); params.set('limit', String(Math.min(200, limits[kind] - values.length)));
+      const page = await request(`/api/model/v1/${kind === 'checkpoints' ? 'history' : kind}?${params}`, { signal });
+      if (signal?.aborted) throw new Error('model_request_cancelled');
+      if (page?.projectId !== raw.projectId || page.revision !== raw.revision || page.sequence !== raw.sequence ||
+        page.transport?.epoch !== raw.transport?.epoch ||
+        JSON.stringify(page.selection) !== JSON.stringify(raw.selection)) throw stalePage();
+      if (page.kind !== kind || !Array.isArray(page.items) || page.items.length > 200 ||
+        page.page?.offset !== values.length || page.page.total !== totals[kind] ||
+        page.page.returned !== page.items.length || (!page.items.length && page.page.nextCursor))
+        throw new Error('invalid_model_page');
+      const bytes = new TextEncoder().encode(jsonBytes(page, 512 * 1024)).length;
+      if (usedBytes + bytes > maxBytes) { incomplete = true; break; }
+      usedBytes += bytes;
+      for (const value of page.items) {
+        if (!id(value?.id) || seenIds.has(value.id)) throw new Error('duplicate_model_record');
+        seenIds.add(value.id); values.push(value);
+      }
+      cursor = page.page.nextCursor;
+      result.pages[kind] = { total: totals[kind], returned: values.length, nextCursor: cursor };
+    }
+    result[kind] = values;
+    retained[kind] = values.length;
+    if (values.length < totals[kind]) incomplete = true;
+  }
+  const ids = new Set(result.entities.map(entity => entity.id));
+  const relations = result.relations.filter(relation => ids.has(relation.source) && ids.has(relation.target));
+  const interpretations = result.interpretations.filter(value => value.entityIds?.every(id => ids.has(id)));
+  if (relations.length !== result.relations.length || interpretations.length !== result.interpretations.length) incomplete = true;
+  result.relations = relations; result.interpretations = interpretations;
+  retained.relations = relations.length; retained.interpretations = interpretations.length;
+  result.partial = incomplete;
+  result.coverage.client = { truncated: incomplete, totals, retained };
+  if (incomplete) result.coverage.truncated = true;
+  return readModel(result);
+}
+
+export function createModelClient({ request, onSnapshot, onError = () => {}, Stream = globalThis.EventSource }) {
+  let epoch = 0, update = 0, stream, controller, hydration, closed = false, selection = {}, latest = null, received = null;
+  function stop() { update++; controller?.abort(); hydration?.abort(); stream?.close(); stream = null; }
+  function duplicate(raw) {
+    const previous = received || latest;
+    if (!previous || previous.projectId !== raw.projectId) return false;
+    if (raw.transport || previous.transport) return raw.transport?.epoch === previous.transport?.epoch &&
+      raw.transport.sequence <= previous.transport.sequence;
+    return raw.sequence <= previous.sequence;
+  }
+  async function accept(raw, streamed = false) {
+    readModel(raw);
+    if (streamed && duplicate(raw)) return;
+    received = raw;
+    hydration?.abort();
+    const active = new AbortController(), mine = ++update;
+    hydration = active;
+    let model, current = raw;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        model = await hydrateModel(current, { request, selection, signal: active.signal });
+        break;
+      } catch (error) {
+        if (active.signal.aborted || mine !== update || closed) return;
+        if (error.status !== 409) throw error;
+        current = await request(`/api/model/v1/snapshot${modelQuery(selection)}`, { signal: active.signal });
+      }
+    }
+    // A continuously changing scope can invalidate all page cursors. Its fresh
+    // first page is still consistent; retain it with explicit partial coverage.
+    if (!model) model = await hydrateModel(current, { fetchPages: false });
+    if (active.signal.aborted || mine !== update || closed) return;
+    const sameEpoch = !latest?.transport || latest.transport.epoch === model.transport?.epoch;
+    latest = model;
+    received = model;
+    onSnapshot(model, streamed && sameEpoch);
+  }
+  async function open(next = selection) {
+    selection = { ...next };
+    stop();
+    const mine = ++epoch;
+    controller = new AbortController();
+    try {
+      const model = await request(`/api/model/v1/snapshot${modelQuery(selection)}`, { signal: controller.signal });
+      if (closed || mine !== epoch) return false;
+      await accept(model);
+      if (closed || mine !== epoch) return false;
+      if (!selection.checkpoint && Stream) {
+        const active = new Stream(`/api/model/v1/events${modelQuery(selection)}`, { withCredentials: true });
+        stream = active;
+        active.addEventListener('snapshot', event => {
+          if (closed || stream !== active) return;
+          try {
+            if (event.data.length > 8 * 1024 * 1024) throw new Error('model_too_large');
+            const raw = JSON.parse(event.data);
+            if (event.lastEventId && raw.transport?.eventId !== event.lastEventId) throw new Error('invalid_model_event');
+            void accept(raw, true).catch(() => onError('An invalid model update was ignored. Reconnect to restore the view.'));
+          } catch { onError('An invalid model update was ignored. Reconnect to restore the view.'); }
+        });
+        active.addEventListener('reset', () => { if (stream === active) void open(); });
+        for (const type of ['unavailable', 'closed', 'revoked', 'expired'])
+          active.addEventListener(type, () => { if (stream === active) void open(); });
+        active.addEventListener('error', () => {
+          if (stream === active) onError('Model connection interrupted. The last received view is retained.');
+        });
+      }
+      return true;
+    } catch (error) {
+      if (!closed && mine === epoch && ![404, 405].includes(error.status)) onError('Model views unavailable. The code map remains available.');
+      return false;
+    }
+  }
+  return { open, suspend() { epoch++; stop(); }, close() { closed = true; epoch++; stop(); } };
+}