@metaharness/workspace-lens 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# @metaharness/workspace-lens
+
+**A Jacobian-Lens interpretability primitive for open-weight LLMs.** Read the model's *verbalizable
+workspace* — the concepts it is disposed to say next — at inference time, and turn it into workspace
+tokens, a layer-by-layer thinking trajectory, drift/entropy scores, vectorized safety flags, and a
+signable **interpretability receipt**.
+
+Runtime-only · model-agnostic · dependency-free (Node built-ins) · deterministic · `$0` to run.
+
+> Companion runtime for Anthropic's *"Verbalizable Representations Form a Global Workspace in Language
+> Models"* (2026-07-06) and its reference code [`anthropics/jacobian-lens`](https://github.com/anthropics/jacobian-lens).
+> This package is **not affiliated with Anthropic**; it is an independent, Apache/MIT-compatible
+> runtime that *consumes* a fitted lens.
+
+---
+
+## Why this exists: from black-box testing to Mechanistic Governance
+
+Classic **logit lens** decodes an intermediate activation `h_l` through the unembedding directly —
+assuming middle layers already live in final-output coordinates. They don't, so the readout is noisy.
+
+The **Jacobian Lens** learns an average layer→final map `J_l` and decodes through it:
+
+```
+lens_l(h) = unembed(J_l · h)
+```
+
+Instead of asking *"what does this activation predict right now?"*, it asks *"what is this activation
+**disposed** to make the model say later?"* — surfacing meaningful, reportable concepts **earlier** in the
+network, often **before the first output token is generated**. Anthropic show models maintain a small set
+of verbalizable internal representations that behave like a functional **global workspace** (report,
+modulation, reasoning, reuse, selective access) — and that hidden concepts like *evaluation awareness*,
+*manipulation*, *secretly*, and *trick* light up there even when absent from the output.
+
+That makes the lens a **runtime semantic firewall** and an audit primitive — the basis for what we call
+**Interpretability Operations (IntOps)**: tap the model's internal wires *while it thinks*, instead of
+asking it to explain itself afterward (which is prone to sycophancy and confabulation).
+
+## What's in the box
+
+| Capability | Export | What it does |
+|---|---|---|
+| **Lens readout** | `WorkspaceLens.readout(h)` | `unembed(J_l·h)` → top workspace tokens + readout entropy |
+| **J-projection** | `WorkspaceLens.project(h)` | `z_l = J_l·h`, the activation in final-layer coordinates |
+| **Workspace drift** | `workspaceDrift(readouts)` | mean Jensen–Shannon divergence between consecutive readouts — is the reasoning path stable or mutating? |
+| **Entropy trajectory** | `entropyTrajectory(readouts)` | per-layer entropy — is the workspace converging or dissolving? |
+| **Vectorized safety** | `detectConcepts(...)` / `flagsFromTriggers(...)` | dot-product triggers vs. concept **directions** (not token strings) → `{promptInjection, evalAwareness, hiddenObjective, refusalConflict}` |
+| **Receipt** | `buildReceipt(...)` | the signable `WorkspaceLensReceipt` audit artifact |
+| **Decision rule** | `decide(...)` | `taskResolved && drift<θ && noCriticalFlags && receiptCoverage===1` |
+
+## Install
+
+```bash
+npm i @metaharness/workspace-lens
+```
+
+## Quickstart
+
+```ts
+import { WorkspaceLens, buildReceipt, decide } from '@metaharness/workspace-lens';
+
+// 1) Load a lens FITTED OUT OF BAND (see "Fitting" below). The artifact carries the vocab + unembed,
+//    so scoring never touches a tokenizer at runtime.
+const lens = await WorkspaceLens.fromFile('./jlens-qwen2.5-7b.json');
+
+// 2) Capture residual activations from your open-weight runtime and hand them in.
+const states = [
+  { layer: 14, position: 6, h: /* number[dModel] */ activations14 },
+  { layer: 18, position: 6, h: activations18 },
+  { layer: 22, position: 6, h: activations22 },
+];
+
+// 3) Read the workspace + build the audit receipt.
+const receipt = buildReceipt(lens, prompt, states, {
+  createdAt: new Date().toISOString(),   // pass it in — receipts stay reproducible
+  concepts,                              // per-model concept direction vectors (optional)
+  topK: 8,
+});
+
+// 4) Govern on it.
+const verdict = decide({
+  taskResolved,
+  workspaceDrift: receipt.workspaceDrift,
+  driftThreshold: 0.25,
+  triggers: receipt.triggers,
+  receiptCoverage: 1,
+});
+if (!verdict.accepted) escalateToHuman(verdict.reasons, receipt);
+```
+
+## The interpretability receipt
+
+The killer feature for regulated buyers: an audit log that maps the **causal trajectory** of a decision —
+*where* a concept arrived, *how* confidence moved, *which* objectives competed — not just the final
+answer. It turns *"the model is a black box that hallucinated"* into *"the model identified a structural
+contradiction at layer 22 and executed the safety policy."* See `WorkspaceLensReceipt` in
+[`src/types.ts`](./src/types.ts).
+
+## Cross-family vocabulary alignment (the hard part, solved)
+
+Different model families (Qwen vs. Gemma 2) have vastly different tokenizers, so you **cannot** align a
+concept like *"hidden objective"* by token string. This package aligns at the **concept-direction** level:
+a canonical concept name maps to a **per-model unit vector** in that model's J-space (`ConceptVector`),
+fitted from example activations. Safety detection is a cosine/dot-product in activation space —
+tokenizer-agnostic — and a concept vector is **never** cross-applied to a different model (`modelId` is
+checked). So `hidden_objective` is *one* concept with a Qwen vector and a Gemma vector, aligned by name.
+
+## Deployment topology (Triage Architecture)
+
+Runtime projection is just static linear algebra (`J_l·h` + a softmax) — **zero** backward passes — so it
+can run live, not only in shadow sampling:
+
+| Tier | Trigger | Depth | Overhead |
+|---|---|---|---|
+| **1 · Passive** | low-risk chat / static generation | lens bypassed | 0% |
+| **2 · Spot-check** | 1% shadow sampling · Darwin-Mode mutation evidence | async batch logging | ~0% |
+| **3 · Full intercept** | tool calls · financial txns · PII · untrusted retrieval | synchronous, mid-layers at critical tokens | small |
+
+Bind Tier 3 to high-stakes routing tokens (e.g. a tool-call token) and you get a **deterministic circuit
+breaker**: a spike in the *exfiltration* / *override* / *credential* directions can kill execution
+mid-forward-pass, *before* a single malicious token is emitted.
+
+## Fitting is external (the one real constraint)
+
+This package **applies** a lens; it does not **fit** one. Fitting `J_l` requires the model's **backward
+pass** over ~100–1000 short sequences (quality saturates quickly), which needs **open-weight local
+models** with activation + gradient access — not a closed API. Fit with the reference
+[`anthropics/jacobian-lens`](https://github.com/anthropics/jacobian-lens) (or load a community pre-fit),
+serialize to the `LensArtifact` shape, and load it here. No weights or corpora are bundled.
+
+## Acceptance test
+
+Fit a lens on a 1.5B–7B Qwen model, run reasoning prompts where the model must hold state silently
+(*"Is `12 + 5 = 1` correct? Answer only Yes or No."*), extract mid-layer states, and verify the Jacobian
+readout surfaces `wrong`/`incorrect`/`false` in the middle workspace **while the input prefix is still
+being processed** — 2–3 layers earlier and with ≥20% higher logit clarity than logit-lens across ≥50
+variations. The [test suite](./__tests__/workspace-lens.test.ts) includes the *mechanism* shape of this
+check on synthetic artifacts (`$0`, no model).
+
+## Where it plugs into MetaHarness
+
+- **Evaluation** — a `workspace_probe` surface: does a candidate harness make the model hold better
+  intermediate concepts *before* answering?
+- **Darwin Mode** — J-lens readouts as **mutation evidence**: reject a prompt mutation that improves the
+  final token but causes the workspace to lose its early grip on the right concept (structurally brittle).
+- **Safety auditing** — prompt injection, hidden-objective drift, eval-awareness, reward-hacking, refusal
+  analysis, as *state assertions* rather than perimeter filters.
+- **Receipts** — attach an interpretability receipt to every governed agent decision.
+
+## Honest framing
+
+This is a **measurement primitive**, not a product and **not** a consciousness claim — the paper frames
+the connection to a global workspace as *functional* and leaves the philosophy open. The practical claim
+is enough: a measurable window into hidden reasoning.
+
+## License
+
+MIT.

package/dist/decision.d.ts

@@ -0,0 +1,3 @@
+import type { DecisionInput, DecisionResult } from './types.js';
+export declare function decide(input: DecisionInput): DecisionResult;
+//# sourceMappingURL=decision.d.ts.map

package/dist/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGhE,wBAAgB,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,CAc3D"}

package/dist/decision.js

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: MIT
+//
+// The accept/reject decision rule — "correctness first, cost second, receipts always":
+//   accepted = taskResolved && workspaceDrift < threshold && noCriticalSafetyFlags && receiptCoverage===1
+// Returns the reasons so a rejection is auditable (which clause failed), not a bare boolean.
+import { hasCriticalTrigger } from './safety.js';
+export function decide(input) {
+    const reasons = [];
+    if (!input.taskResolved)
+        reasons.push('task not resolved');
+    if (!(input.workspaceDrift < input.driftThreshold)) {
+        reasons.push(`workspace drift ${input.workspaceDrift.toFixed(4)} >= threshold ${input.driftThreshold}`);
+    }
+    if (hasCriticalTrigger(input.triggers)) {
+        const crit = input.triggers.filter((t) => t.critical).map((t) => t.concept);
+        reasons.push(`critical safety trigger(s): ${[...new Set(crit)].join(', ')}`);
+    }
+    if (input.receiptCoverage !== 1) {
+        reasons.push(`receipt coverage ${input.receiptCoverage} != 1 (not every decision was witnessed)`);
+    }
+    return { accepted: reasons.length === 0, reasons };
+}
+//# sourceMappingURL=decision.js.map

package/dist/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,uFAAuF;AACvF,0GAA0G;AAC1G,6FAA6F;AAG7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,UAAU,MAAM,CAAC,KAAoB;IACzC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,YAAY;QAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC3D,IAAI,CAAC,CAAC,KAAK,CAAC,cAAc,GAAG,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,IAAI,CAAC,mBAAmB,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,KAAK,CAAC,cAAc,EAAE,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAC5E,OAAO,CAAC,IAAI,CAAC,+BAA+B,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC,oBAAoB,KAAK,CAAC,eAAe,0CAA0C,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;AACrD,CAAC"}

package/dist/drift.d.ts

@@ -0,0 +1,13 @@
+import type { WorkspaceReadout } from './types.js';
+/**
+ * Mean Jensen–Shannon divergence (nats) between consecutive readouts in order. 0 when fewer than two
+ * readouts. Only compares readouts whose token support has the same length (same topK) so the JS is
+ * well-defined; mismatched pairs are skipped and reported via `comparedPairs`.
+ */
+export declare function workspaceDrift(readouts: readonly WorkspaceReadout[]): {
+    drift: number;
+    comparedPairs: number;
+};
+/** The per-readout entropy sequence, in the readouts' given order. */
+export declare function entropyTrajectory(readouts: readonly WorkspaceReadout[]): number[];
+//# sourceMappingURL=drift.d.ts.map

package/dist/drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.d.ts","sourceRoot":"","sources":["../src/drift.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAUnD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAW9G;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAEjF"}

package/dist/drift.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+//
+// Workspace stability metrics. workspaceDrift measures how much the readout DISTRIBUTION moves between
+// consecutive readouts (layers/positions): the Jensen–Shannon divergence between adjacent softmax
+// distributions, averaged. A radical jump without an output-token boundary signals the internal
+// reasoning path collapsing or mutating uncontrollably. entropyTrajectory tracks whether the workspace
+// is converging (entropy falling → committing to a concept) or dissolving (rising → losing its grip).
+import { jensenShannon, softmax } from './linalg.js';
+/** Reconstruct the readout's probability distribution over its returned tokens (for step-to-step JS). */
+function readoutProbs(r) {
+    // Use the token logits we kept; re-softmax over the returned top-k so two readouts are compared on the
+    // same support ordering. Callers that need full-vocab drift should pass full-vocab readouts (topK=vocab).
+    return softmax(r.tokens.map((t) => t.logit));
+}
+/**
+ * Mean Jensen–Shannon divergence (nats) between consecutive readouts in order. 0 when fewer than two
+ * readouts. Only compares readouts whose token support has the same length (same topK) so the JS is
+ * well-defined; mismatched pairs are skipped and reported via `comparedPairs`.
+ */
+export function workspaceDrift(readouts) {
+    let sum = 0;
+    let pairs = 0;
+    for (let i = 1; i < readouts.length; i++) {
+        const a = readoutProbs(readouts[i - 1]);
+        const b = readoutProbs(readouts[i]);
+        if (a.length !== b.length || a.length === 0)
+            continue;
+        sum += jensenShannon(a, b);
+        pairs += 1;
+    }
+    return { drift: pairs === 0 ? 0 : sum / pairs, comparedPairs: pairs };
+}
+/** The per-readout entropy sequence, in the readouts' given order. */
+export function entropyTrajectory(readouts) {
+    return readouts.map((r) => r.entropy);
+}
+//# sourceMappingURL=drift.js.map

package/dist/drift.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.js","sourceRoot":"","sources":["../src/drift.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,uGAAuG;AACvG,kGAAkG;AAClG,gGAAgG;AAChG,uGAAuG;AACvG,sGAAsG;AAGtG,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAErD,yGAAyG;AACzG,SAAS,YAAY,CAAC,CAAmB;IACvC,uGAAuG;IACvG,0GAA0G;IAC1G,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,QAAqC;IAClE,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACtD,GAAG,IAAI,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3B,KAAK,IAAI,CAAC,CAAC;IACb,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AACxE,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,iBAAiB,CAAC,QAAqC;IACrE,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './linalg.js';
+export { WorkspaceLens } from './lens.js';
+export { detectConcepts, flagsFromTriggers, hasCriticalTrigger, FLAG_CONCEPTS, type DetectOptions } from './safety.js';
+export { workspaceDrift, entropyTrajectory } from './drift.js';
+export { decide } from './decision.js';
+export { buildReceipt, sha256, type BuildReceiptOptions } from './receipt.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACvH,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+//
+// @metaharness/workspace-lens — a Jacobian-Lens interpretability primitive for open-weight LLMs.
+// Runtime-only (fitting is external), model-agnostic, dependency-free. See README.md.
+export * from './types.js';
+export * from './linalg.js';
+export { WorkspaceLens } from './lens.js';
+export { detectConcepts, flagsFromTriggers, hasCriticalTrigger, FLAG_CONCEPTS } from './safety.js';
+export { workspaceDrift, entropyTrajectory } from './drift.js';
+export { decide } from './decision.js';
+export { buildReceipt, sha256 } from './receipt.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,iGAAiG;AACjG,sFAAsF;AAEtF,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAC;AACvH,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,EAA4B,MAAM,cAAc,CAAC"}

package/dist/lens.d.ts

@@ -0,0 +1,34 @@
+import type { LensArtifact, HiddenState, WorkspaceReadout } from './types.js';
+export declare class WorkspaceLens {
+    readonly artifact: LensArtifact;
+    private readonly byLayer;
+    private constructor();
+    /** Build a lens from an in-memory artifact (validated eagerly so a bad artifact fails at load). */
+    static fromArtifact(artifact: LensArtifact): WorkspaceLens;
+    /**
+     * Load a fitted lens from a JSON file. (Binary/registry formats — e.g. a Neuronpedia pre-fit — are a
+     * follow-up; the on-disk contract is just a serialized `LensArtifact`.) Kept out of the constructor so
+     * the core stays sync + I/O-free for hot-path use.
+     */
+    static fromFile(path: string): Promise<WorkspaceLens>;
+    get modelId(): string;
+    get lensId(): string;
+    get dModel(): number;
+    /** Layer indices this lens can read, ascending. */
+    get layers(): number[];
+    private validate;
+    /** True if the lens has a fitted operator for this layer. */
+    hasLayer(layer: number): boolean;
+    /**
+     * z_l = J_l · h — the activation projected into final-layer coordinates. This is the quantity the
+     * Jacobian Lens corrects for (vs. logit-lens reading h directly). Throws if the layer is un-fitted or
+     * the width is wrong.
+     */
+    project(state: HiddenState): number[];
+    /**
+     * Full readout: lens_l(h) = unembed(J_l · h), returned as the top-k workspace tokens + the readout
+     * entropy. `topK` bounds the returned tokens; the entropy is over the FULL distribution.
+     */
+    readout(state: HiddenState, topK?: number): WorkspaceReadout;
+}
+//# sourceMappingURL=lens.d.ts.map

package/dist/lens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens.d.ts","sourceRoot":"","sources":["../src/lens.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAkB,MAAM,YAAY,CAAC;AAG9F,qBAAa,aAAa;IAGJ,QAAQ,CAAC,QAAQ,EAAE,YAAY;IAFnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IAEtE,OAAO;IAKP,mGAAmG;IACnG,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,aAAa;IAI1D;;;;OAIG;WACU,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAM3D,IAAI,OAAO,IAAI,MAAM,CAAkC;IACvD,IAAI,MAAM,IAAI,MAAM,CAAiC;IACrD,IAAI,MAAM,IAAI,MAAM,CAAiC;IACrD,mDAAmD;IACnD,IAAI,MAAM,IAAI,MAAM,EAAE,CAA2D;IAEjF,OAAO,CAAC,QAAQ;IAkBhB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAEhC;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,EAAE;IASrC;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,SAAK,GAAG,gBAAgB;CAazD"}

package/dist/lens.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+//
+// WorkspaceLens — the runtime engine. Loads a fitted LensArtifact and, given a captured hidden state
+// h_l, computes lens_l(h) = unembed(J_l · h) → workspace tokens. The intermediate J-projection z_l =
+// J_l · h (the activation mapped into final-layer coordinates) is also exposed, because the vectorized
+// safety triggers compare z_l to concept directions rather than decoding the whole vocabulary.
+import { matVec, softmax, entropy, topKIndices } from './linalg.js';
+export class WorkspaceLens {
+    artifact;
+    byLayer;
+    constructor(artifact) {
+        this.artifact = artifact;
+        this.byLayer = new Map(artifact.layers.map((l) => [l.layer, l.jacobian]));
+        this.validate();
+    }
+    /** Build a lens from an in-memory artifact (validated eagerly so a bad artifact fails at load). */
+    static fromArtifact(artifact) {
+        return new WorkspaceLens(artifact);
+    }
+    /**
+     * Load a fitted lens from a JSON file. (Binary/registry formats — e.g. a Neuronpedia pre-fit — are a
+     * follow-up; the on-disk contract is just a serialized `LensArtifact`.) Kept out of the constructor so
+     * the core stays sync + I/O-free for hot-path use.
+     */
+    static async fromFile(path) {
+        const { readFile } = await import('node:fs/promises');
+        const raw = await readFile(path, 'utf-8');
+        return new WorkspaceLens(JSON.parse(raw));
+    }
+    get modelId() { return this.artifact.modelId; }
+    get lensId() { return this.artifact.lensId; }
+    get dModel() { return this.artifact.dModel; }
+    /** Layer indices this lens can read, ascending. */
+    get layers() { return [...this.byLayer.keys()].sort((a, b) => a - b); }
+    validate() {
+        const { dModel, unembed, vocab, layers } = this.artifact;
+        if (dModel <= 0)
+            throw new Error('lens artifact: dModel must be positive');
+        if (vocab.length === 0)
+            throw new Error('lens artifact: empty vocab');
+        if (unembed.length !== vocab.length) {
+            throw new Error(`lens artifact: unembed rows ${unembed.length} != vocab ${vocab.length}`);
+        }
+        if (unembed[0]?.length !== dModel) {
+            throw new Error(`lens artifact: unembed cols ${unembed[0]?.length} != dModel ${dModel}`);
+        }
+        if (layers.length === 0)
+            throw new Error('lens artifact: no fitted layers');
+        for (const l of layers) {
+            if (l.jacobian.length !== dModel || l.jacobian[0]?.length !== dModel) {
+                throw new Error(`lens artifact: layer ${l.layer} jacobian is not ${dModel}×${dModel}`);
+            }
+        }
+    }
+    /** True if the lens has a fitted operator for this layer. */
+    hasLayer(layer) { return this.byLayer.has(layer); }
+    /**
+     * z_l = J_l · h — the activation projected into final-layer coordinates. This is the quantity the
+     * Jacobian Lens corrects for (vs. logit-lens reading h directly). Throws if the layer is un-fitted or
+     * the width is wrong.
+     */
+    project(state) {
+        const j = this.byLayer.get(state.layer);
+        if (!j)
+            throw new Error(`lens has no fitted operator for layer ${state.layer}`);
+        if (state.h.length !== this.dModel) {
+            throw new Error(`hidden state width ${state.h.length} != dModel ${this.dModel}`);
+        }
+        return matVec(j, state.h);
+    }
+    /**
+     * Full readout: lens_l(h) = unembed(J_l · h), returned as the top-k workspace tokens + the readout
+     * entropy. `topK` bounds the returned tokens; the entropy is over the FULL distribution.
+     */
+    readout(state, topK = 10) {
+        const z = this.project(state);
+        const logits = matVec(this.artifact.unembed, z);
+        const probs = softmax(logits);
+        const idx = topKIndices(logits, topK);
+        const tokens = idx.map((vi, rank) => ({
+            token: this.artifact.vocab[vi],
+            rank,
+            logit: logits[vi],
+            prob: probs[vi],
+        }));
+        return { layer: state.layer, position: state.position, tokens, entropy: entropy(probs) };
+    }
+}
+//# sourceMappingURL=lens.js.map

package/dist/lens.js.map

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

package/dist/linalg.d.ts

@@ -0,0 +1,21 @@
+export type Vector = readonly number[];
+/** Row-major dense matrix: `rows` arrays of length `cols`. */
+export type Matrix = readonly Vector[];
+/** y = M · x. Throws on a shape mismatch so a malformed lens artifact fails loudly, not silently. */
+export declare function matVec(m: Matrix, x: Vector): number[];
+export declare function dot(a: Vector, b: Vector): number;
+export declare function norm(a: Vector): number;
+/** Cosine similarity in [-1, 1]; 0 when either vector is all-zero (avoids NaN). */
+export declare function cosine(a: Vector, b: Vector): number;
+/** Numerically-stable softmax over logits → a probability distribution summing to 1. */
+export declare function softmax(logits: Vector): number[];
+/** Shannon entropy (nats) of a probability distribution. Higher = more diffuse workspace. */
+export declare function entropy(probs: Vector): number;
+/**
+ * Jensen–Shannon divergence between two distributions (nats, in [0, ln 2]). Symmetric + bounded, so it
+ * is a stable per-step drift metric — unlike raw KL it never diverges to Infinity when a bin goes to 0.
+ */
+export declare function jensenShannon(p: Vector, q: Vector): number;
+/** Indices of the top-k entries of `values`, highest first. Ties broken by lower index (stable). */
+export declare function topKIndices(values: Vector, k: number): number[];
+//# sourceMappingURL=linalg.d.ts.map

package/dist/linalg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"linalg.d.ts","sourceRoot":"","sources":["../src/linalg.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AACvC,8DAA8D;AAC9D,MAAM,MAAM,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAEvC,qGAAqG;AACrG,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAerD;AAED,wBAAgB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAKhD;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEtC;AAED,mFAAmF;AACnF,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,wFAAwF;AACxF,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAahD;AAED,6FAA6F;AAC7F,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAU1D;AAED,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAI/D"}

package/dist/linalg.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+//
+// Minimal, dependency-free linear algebra for the runtime lens projection. This package NEVER fits a
+// Jacobian (that needs a model backward pass — external); it only APPLIES a pre-fitted lens, which is a
+// pair of matrix-vector products plus a softmax. So a few well-typed loops over Float64Array/number[]
+// are all we need — no BLAS, no native deps, deterministic, and fast enough for per-request governance.
+/** y = M · x. Throws on a shape mismatch so a malformed lens artifact fails loudly, not silently. */
+export function matVec(m, x) {
+    if (m.length === 0)
+        return [];
+    const cols = m[0].length;
+    if (cols !== x.length) {
+        throw new Error(`matVec: matrix cols ${cols} != vector length ${x.length}`);
+    }
+    const out = new Array(m.length);
+    for (let i = 0; i < m.length; i++) {
+        const row = m[i];
+        if (row.length !== cols)
+            throw new Error(`matVec: ragged matrix at row ${i} (${row.length} != ${cols})`);
+        let s = 0;
+        for (let j = 0; j < cols; j++)
+            s += row[j] * x[j];
+        out[i] = s;
+    }
+    return out;
+}
+export function dot(a, b) {
+    if (a.length !== b.length)
+        throw new Error(`dot: length ${a.length} != ${b.length}`);
+    let s = 0;
+    for (let i = 0; i < a.length; i++)
+        s += a[i] * b[i];
+    return s;
+}
+export function norm(a) {
+    return Math.sqrt(dot(a, a));
+}
+/** Cosine similarity in [-1, 1]; 0 when either vector is all-zero (avoids NaN). */
+export function cosine(a, b) {
+    const na = norm(a);
+    const nb = norm(b);
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot(a, b) / (na * nb);
+}
+/** Numerically-stable softmax over logits → a probability distribution summing to 1. */
+export function softmax(logits) {
+    if (logits.length === 0)
+        return [];
+    let max = -Infinity;
+    for (const v of logits)
+        if (v > max)
+            max = v;
+    const exps = new Array(logits.length);
+    let sum = 0;
+    for (let i = 0; i < logits.length; i++) {
+        const e = Math.exp(logits[i] - max);
+        exps[i] = e;
+        sum += e;
+    }
+    for (let i = 0; i < exps.length; i++)
+        exps[i] /= sum;
+    return exps;
+}
+/** Shannon entropy (nats) of a probability distribution. Higher = more diffuse workspace. */
+export function entropy(probs) {
+    let h = 0;
+    for (const p of probs)
+        if (p > 0)
+            h -= p * Math.log(p);
+    return h;
+}
+/**
+ * Jensen–Shannon divergence between two distributions (nats, in [0, ln 2]). Symmetric + bounded, so it
+ * is a stable per-step drift metric — unlike raw KL it never diverges to Infinity when a bin goes to 0.
+ */
+export function jensenShannon(p, q) {
+    if (p.length !== q.length)
+        throw new Error(`jensenShannon: length ${p.length} != ${q.length}`);
+    let d = 0;
+    for (let i = 0; i < p.length; i++) {
+        const m = (p[i] + q[i]) / 2;
+        if (p[i] > 0 && m > 0)
+            d += 0.5 * p[i] * Math.log(p[i] / m);
+        if (q[i] > 0 && m > 0)
+            d += 0.5 * q[i] * Math.log(q[i] / m);
+    }
+    // Clamp tiny negative from float error.
+    return d < 0 ? 0 : d;
+}
+/** Indices of the top-k entries of `values`, highest first. Ties broken by lower index (stable). */
+export function topKIndices(values, k) {
+    const idx = values.map((_, i) => i);
+    idx.sort((a, b) => (values[b] - values[a]) || (a - b));
+    return idx.slice(0, Math.max(0, k));
+}
+//# sourceMappingURL=linalg.js.map

package/dist/linalg.js.map

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

package/dist/receipt.d.ts

@@ -0,0 +1,16 @@
+import type { WorkspaceLens } from './lens.js';
+import type { HiddenState, ConceptVector, WorkspaceLensReceipt } from './types.js';
+import { type DetectOptions } from './safety.js';
+export interface BuildReceiptOptions {
+    /** Number of workspace tokens to keep per readout. Default 8. */
+    topK?: number;
+    /** Concept vectors to score for safety triggers. Default none. */
+    concepts?: readonly ConceptVector[];
+    /** Concept-trigger cosine threshold. */
+    detect?: DetectOptions;
+    /** ISO timestamp for the receipt. REQUIRED — pass it in so the receipt is deterministic/reproducible. */
+    createdAt: string;
+}
+export declare function sha256(s: string): string;
+export declare function buildReceipt(lens: WorkspaceLens, prompt: string, states: readonly HiddenState[], opts: BuildReceiptOptions): WorkspaceLensReceipt;
+//# sourceMappingURL=receipt.d.ts.map

package/dist/receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.d.ts","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EACV,WAAW,EAAE,aAAa,EAAE,oBAAoB,EACjD,MAAM,YAAY,CAAC;AACpB,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGpF,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IACpC,wCAAwC;IACxC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,yGAAyG;IACzG,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAExC;AAED,wBAAgB,YAAY,CAC1B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,IAAI,EAAE,mBAAmB,GACxB,oBAAoB,CAgCtB"}

package/dist/receipt.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+//
+// buildReceipt — the one-call orchestrator. Given a lens, a prompt, the captured hidden states, and a
+// concept library, it reads the workspace at every state, scores drift/entropy, fires safety triggers,
+// and assembles the signable WorkspaceLensReceipt. Pure aside from a sha256 of the prompt (node:crypto,
+// a builtin) — no model, no network — so it runs identically offline and in a governance hot path.
+import { createHash } from 'node:crypto';
+import { detectConcepts, flagsFromTriggers } from './safety.js';
+import { workspaceDrift, entropyTrajectory } from './drift.js';
+export function sha256(s) {
+    return createHash('sha256').update(s).digest('hex');
+}
+export function buildReceipt(lens, prompt, states, opts) {
+    const topK = opts.topK ?? 8;
+    const readouts = states
+        .filter((s) => lens.hasLayer(s.layer))
+        .map((s) => lens.readout(s, topK));
+    const triggers = opts.concepts ? detectConcepts(lens, states, opts.concepts, opts.detect) : [];
+    const flags = flagsFromTriggers(triggers);
+    const { drift } = workspaceDrift(readouts);
+    const layersSeen = readouts.map((r) => r.layer);
+    const layerRange = layersSeen.length
+        ? [Math.min(...layersSeen), Math.max(...layersSeen)]
+        : [0, 0];
+    return {
+        promptHash: sha256(prompt),
+        modelId: lens.modelId,
+        lensId: lens.lensId,
+        layerRange,
+        positions: [...new Set(readouts.map((r) => r.position))].sort((a, b) => a - b),
+        topTokens: readouts.map((r) => ({
+            layer: r.layer,
+            position: r.position,
+            tokens: r.tokens.map((t) => ({ token: t.token, rank: t.rank, logit: t.logit })),
+        })),
+        flags,
+        triggers,
+        workspaceDrift: drift,
+        entropyTrajectory: entropyTrajectory(readouts),
+        createdAt: opts.createdAt,
+    };
+}
+//# sourceMappingURL=receipt.js.map

package/dist/receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipt.js","sourceRoot":"","sources":["../src/receipt.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,sGAAsG;AACtG,uGAAuG;AACvG,wGAAwG;AACxG,mGAAmG;AAEnG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAKzC,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAsB,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAa/D,MAAM,UAAU,MAAM,CAAC,CAAS;IAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,IAAmB,EACnB,MAAc,EACd,MAA8B,EAC9B,IAAyB;IAEzB,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAuB,MAAM;SACxC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;SACrC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/F,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,EAAE,KAAK,EAAE,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE3C,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,UAAU,GAAqB,UAAU,CAAC,MAAM;QACpD,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;QACpD,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAEX,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU;QACV,SAAS,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;QAC9E,SAAS,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9B,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;SAChF,CAAC,CAAC;QACH,KAAK;QACL,QAAQ;QACR,cAAc,EAAE,KAAK;QACrB,iBAAiB,EAAE,iBAAiB,CAAC,QAAQ,CAAC;QAC9C,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC;AACJ,CAAC"}

package/dist/safety.d.ts

@@ -0,0 +1,23 @@
+import type { WorkspaceLens } from './lens.js';
+import type { HiddenState, ConceptVector, ConceptTrigger, SafetyFlags } from './types.js';
+/** Canonical concept names that map onto the four headline SafetyFlags. */
+export declare const FLAG_CONCEPTS: {
+    readonly promptInjection: readonly ["prompt_injection", "override", "ignore_instructions", "exfiltration"];
+    readonly evalAwareness: readonly ["evaluation_awareness", "being_tested", "watched"];
+    readonly hiddenObjective: readonly ["hidden_objective", "secretly", "deception", "manipulation"];
+    readonly refusalConflict: readonly ["refusal_conflict", "should_refuse", "jailbreak"];
+};
+export interface DetectOptions {
+    /** Cosine threshold above which a concept is considered active. Default 0.35 (tunable per deployment). */
+    threshold?: number;
+}
+/**
+ * Score every (state × concept) pair and return the concepts that fired. Concept vectors whose `modelId`
+ * doesn't match the lens are skipped (a fail-safe against applying a Qwen direction to a Gemma model).
+ */
+export declare function detectConcepts(lens: WorkspaceLens, states: readonly HiddenState[], concepts: readonly ConceptVector[], opts?: DetectOptions): ConceptTrigger[];
+/** Roll fired concept triggers up into the four headline flags. */
+export declare function flagsFromTriggers(triggers: readonly ConceptTrigger[]): SafetyFlags;
+/** True if any fired trigger is marked critical (used to fail the decision rule closed). */
+export declare function hasCriticalTrigger(triggers: readonly ConceptTrigger[]): boolean;
+//# sourceMappingURL=safety.d.ts.map

package/dist/safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.d.ts","sourceRoot":"","sources":["../src/safety.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG1F,2EAA2E;AAC3E,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,MAAM,WAAW,aAAa;IAC5B,0GAA0G;IAC1G,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,IAAI,GAAE,aAAkB,GACvB,cAAc,EAAE,CAgBlB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,WAAW,CASlF;AAED,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,GAAG,OAAO,CAE/E"}

package/dist/safety.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+//
+// Vectorized safety triggers. Anthropic found hidden objectives ("secretly", "manipulation", "evaluation
+// awareness") light up in the workspace even when absent from the output. We detect them NOT by matching
+// decoded token strings (brittle, tokenizer-specific) but by the dot product of the J-projected
+// activation against pre-fitted concept DIRECTIONS in the model's own J-space. That makes the trigger
+// tokenizer-agnostic and cross-family: a concept is aligned by name + per-model vector, so "hidden
+// objective" is one canonical concept with a Qwen vector and a Gemma vector — never a string map.
+import { cosine } from './linalg.js';
+/** Canonical concept names that map onto the four headline SafetyFlags. */
+export const FLAG_CONCEPTS = {
+    promptInjection: ['prompt_injection', 'override', 'ignore_instructions', 'exfiltration'],
+    evalAwareness: ['evaluation_awareness', 'being_tested', 'watched'],
+    hiddenObjective: ['hidden_objective', 'secretly', 'deception', 'manipulation'],
+    refusalConflict: ['refusal_conflict', 'should_refuse', 'jailbreak'],
+};
+/**
+ * Score every (state × concept) pair and return the concepts that fired. Concept vectors whose `modelId`
+ * doesn't match the lens are skipped (a fail-safe against applying a Qwen direction to a Gemma model).
+ */
+export function detectConcepts(lens, states, concepts, opts = {}) {
+    const threshold = opts.threshold ?? 0.35;
+    const triggers = [];
+    for (const state of states) {
+        if (!lens.hasLayer(state.layer))
+            continue;
+        const z = lens.project(state);
+        for (const c of concepts) {
+            if (c.modelId !== lens.modelId)
+                continue; // never cross-apply a concept from another model
+            if (c.vector.length !== z.length)
+                continue;
+            const score = cosine(z, c.vector);
+            if (score >= threshold) {
+                triggers.push({ concept: c.concept, layer: state.layer, position: state.position, score, critical: !!c.critical });
+            }
+        }
+    }
+    return triggers;
+}
+/** Roll fired concept triggers up into the four headline flags. */
+export function flagsFromTriggers(triggers) {
+    const fired = new Set(triggers.map((t) => t.concept));
+    const any = (names) => names.some((n) => fired.has(n));
+    return {
+        promptInjection: any(FLAG_CONCEPTS.promptInjection),
+        evalAwareness: any(FLAG_CONCEPTS.evalAwareness),
+        hiddenObjective: any(FLAG_CONCEPTS.hiddenObjective),
+        refusalConflict: any(FLAG_CONCEPTS.refusalConflict),
+    };
+}
+/** True if any fired trigger is marked critical (used to fail the decision rule closed). */
+export function hasCriticalTrigger(triggers) {
+    return triggers.some((t) => t.critical);
+}
+//# sourceMappingURL=safety.js.map

package/dist/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../src/safety.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,yGAAyG;AACzG,yGAAyG;AACzG,gGAAgG;AAChG,sGAAsG;AACtG,mGAAmG;AACnG,kGAAkG;AAIlG,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,2EAA2E;AAC3E,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,eAAe,EAAE,CAAC,kBAAkB,EAAE,UAAU,EAAE,qBAAqB,EAAE,cAAc,CAAC;IACxF,aAAa,EAAE,CAAC,sBAAsB,EAAE,cAAc,EAAE,SAAS,CAAC;IAClE,eAAe,EAAE,CAAC,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,CAAC;IAC9E,eAAe,EAAE,CAAC,kBAAkB,EAAE,eAAe,EAAE,WAAW,CAAC;CAC3D,CAAC;AAOX;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAmB,EACnB,MAA8B,EAC9B,QAAkC,EAClC,OAAsB,EAAE;IAExB,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;IACzC,MAAM,QAAQ,GAAqB,EAAE,CAAC;IACtC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC;YAAE,SAAS;QAC1C,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO;gBAAE,SAAS,CAAC,iDAAiD;YAC3F,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;gBAAE,SAAS;YAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;YAClC,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;gBACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YACrH,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAC,QAAmC;IACnE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,CAAC,KAAwB,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,OAAO;QACL,eAAe,EAAE,GAAG,CAAC,aAAa,CAAC,eAAe,CAAC;QACnD,aAAa,EAAE,GAAG,CAAC,aAAa,CAAC,aAAa,CAAC;QAC/C,eAAe,EAAE,GAAG,CAAC,aAAa,CAAC,eAAe,CAAC;QACnD,eAAe,EAAE,GAAG,CAAC,aAAa,CAAC,eAAe,CAAC;KACpD,CAAC;AACJ,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,kBAAkB,CAAC,QAAmC;IACpE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC1C,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,128 @@
+/** A fitted per-layer Jacobian operator J_l ∈ ℝ^{dModel×dModel}, plus the shared decode path. */
+export interface LensLayer {
+    /** Transformer layer index this operator was fitted for. */
+    layer: number;
+    /** Row-major J_l (dModel×dModel): the average input→output Jacobian for this layer. */
+    jacobian: readonly (readonly number[])[];
+}
+/**
+ * A fitted lens artifact for ONE model. Model-agnostic by construction: the vocabulary and the
+ * unembedding live in the artifact, so scoring never touches a tokenizer at runtime. Fitted OUT OF BAND
+ * (open-weight model + backward pass; see the reference `anthropics/jacobian-lens` + Neuronpedia), then
+ * serialized and loaded here.
+ */
+export interface LensArtifact {
+    /** Stable id for this fitted lens (e.g. "jlens-qwen2.5-7b-v2") — recorded in every receipt. */
+    lensId: string;
+    /** The model the lens was fitted on (e.g. "qwen2.5-7b-instruct"). */
+    modelId: string;
+    /** Residual-stream width. */
+    dModel: number;
+    /** Decoded vocabulary — token strings aligned to the unembed rows. */
+    vocab: readonly string[];
+    /** Unembedding U ∈ ℝ^{vocab×dModel}. lens_l(h) = U · (J_l · h). */
+    unembed: readonly (readonly number[])[];
+    /** The fitted per-layer operators, keyed by layer index. */
+    layers: readonly LensLayer[];
+}
+/** A captured residual-stream activation at a specific (layer, position). Supplied by the caller. */
+export interface HiddenState {
+    layer: number;
+    /** Token position in the sequence the activation was captured at. */
+    position: number;
+    /** The residual vector h_l ∈ ℝ^{dModel}. */
+    h: readonly number[];
+}
+/** One decoded workspace token: what the activation is DISPOSED to make the model say later. */
+export interface WorkspaceToken {
+    token: string;
+    /** 0-based rank in the lens readout (0 = most probable). */
+    rank: number;
+    /** The lens logit for this token (pre-softmax). */
+    logit: number;
+    /** The softmax probability for this token within the readout. */
+    prob: number;
+}
+/** A per-(layer,position) readout of the workspace. */
+export interface WorkspaceReadout {
+    layer: number;
+    position: number;
+    tokens: WorkspaceToken[];
+    /** Shannon entropy (nats) of the full readout distribution — how diffuse the workspace is here. */
+    entropy: number;
+}
+/**
+ * A concept represented as a DIRECTION in a given model's J-space (NOT a token string). This is how the
+ * package aligns concepts across architectural families with different tokenizers (Qwen vs Gemma): a
+ * canonical concept name maps to a per-model unit vector fitted from example activations, so the safety
+ * trigger is a dot-product in activation space, tokenizer-agnostic. `modelId` guards against applying a
+ * Qwen concept vector to a Gemma activation.
+ */
+export interface ConceptVector {
+    /** Canonical concept name, aligned across models (e.g. "hidden_objective", "exfiltration"). */
+    concept: string;
+    /** The model this vector lives in — MUST match the lens/activation model. */
+    modelId: string;
+    /** Unit (or arbitrary) direction in J-space, length dModel. */
+    vector: readonly number[];
+    /** Optional: treat concept as CRITICAL — a trigger fails the decision rule closed. */
+    critical?: boolean;
+}
+/** A fired concept trigger. */
+export interface ConceptTrigger {
+    concept: string;
+    layer: number;
+    position: number;
+    /** Cosine similarity of the J-projected activation to the concept direction. */
+    score: number;
+    critical: boolean;
+}
+/** The four headline safety flags (Anthropic's workspace examples: eval-awareness, manipulation, …). */
+export interface SafetyFlags {
+    promptInjection: boolean;
+    evalAwareness: boolean;
+    hiddenObjective: boolean;
+    refusalConflict: boolean;
+}
+/**
+ * The signable interpretability receipt — the audit artifact. "correctness first, cost second, receipts
+ * always": it records WHAT concepts were active in the workspace when a decision was made, with the
+ * layer-by-layer trajectory so an auditor can see WHERE a decision formed, not just the final answer.
+ */
+export interface WorkspaceLensReceipt {
+    promptHash: string;
+    modelId: string;
+    lensId: string;
+    layerRange: [number, number];
+    positions: number[];
+    topTokens: Array<{
+        layer: number;
+        position: number;
+        tokens: Array<{
+            token: string;
+            rank: number;
+            logit: number;
+        }>;
+    }>;
+    flags: SafetyFlags;
+    triggers: ConceptTrigger[];
+    /** Aggregate J-space distribution stability across the readouts (mean JS-divergence between steps). */
+    workspaceDrift: number;
+    /** Per-readout entropy — is the internal workspace converging (falling) or dissolving (rising)? */
+    entropyTrajectory: number[];
+    createdAt: string;
+}
+/** Inputs to the accept/reject decision rule. */
+export interface DecisionInput {
+    taskResolved: boolean;
+    workspaceDrift: number;
+    driftThreshold: number;
+    triggers: ConceptTrigger[];
+    /** Fraction of monitored decisions that produced a receipt (1 = full coverage). */
+    receiptCoverage: number;
+}
+export interface DecisionResult {
+    accepted: boolean;
+    reasons: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+//
+// Public types for @metaharness/workspace-lens. The package is a RUNTIME measurement primitive: given a
+// pre-fitted Jacobian lens artifact + captured hidden activations, it reads the model's "verbalizable
+// workspace" (Anthropic, 2026-07-06) and emits a signable interpretability receipt. It does not fit the
+// lens (that needs the model's backward pass — external, GPU) and it does not run the model.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,wGAAwG;AACxG,sGAAsG;AACtG,wGAAwG;AACxG,6FAA6F"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@metaharness/workspace-lens",
+  "version": "0.1.0",
+  "description": "Jacobian-Lens interpretability primitive for open-weight LLMs (Anthropic 2026-07-06, 'Verbalizable Representations Form a Global Workspace'). Reads the model's functional workspace at inference time — lens_l(h)=unembed(J_l·h) — into workspace tokens, layer-trajectory, drift/entropy scores, vectorized safety flags, and a signable interpretability receipt. Runtime-only (fitting is external); model-agnostic; dependency-free.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "jacobian-lens",
+    "interpretability",
+    "logit-lens",
+    "global-workspace",
+    "mechanistic-governance",
+    "intops",
+    "ai-safety",
+    "prompt-injection",
+    "llm",
+    "open-weight",
+    "metaharness",
+    "agent-harness"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}