@davesheffer/hunch 1.32.8 → 1.33.0

package/dist/core/types.d.ts

@@ -7,7 +7,7 @@
  */
 import { z } from "zod";
 import { ProvenanceSchema, isCredentialFreeText, type Provenance } from "./provenance.js";
-import { type ActionReceipt, type Commitment, type DerivedState, type ExternalEntity, type StateRelationship } from "./stateRecords.js";
+import { type Convention, type ActionReceipt, type Commitment, type DerivedState, type ExternalEntity, type StateRelationship } from "./stateRecords.js";
 export { ProvenanceSchema, isCredentialFreeText };
 export type { Provenance };
 export declare const ComponentKind: z.ZodEnum<{
@@ -335,6 +335,11 @@ export declare const PremiseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Premise = z.infer<typeof PremiseSchema>;
 export declare const DecisionSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     title: z.ZodString;
     topic: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -416,6 +421,11 @@ export declare const BugLineageSchema: z.ZodObject<{
 export type BugLineage = z.infer<typeof BugLineageSchema>;
 /** A bug with root cause and lineage (introduced → fixed → recurred). */
 export declare const BugSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     title: z.ZodString;
     symptom: z.ZodDefault<z.ZodString>;
@@ -452,6 +462,11 @@ export declare const BugSchema: z.ZodObject<{
 export type Bug = z.infer<typeof BugSchema>;
 /** An invariant the system must respect. */
 export declare const ConstraintSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     type: z.ZodDefault<z.ZodEnum<{
         security: "security";
@@ -526,6 +541,11 @@ export type Runbook = z.infer<typeof RunbookSchema>;
  *  never enters any block path. Lifecycle is `triage`, not valid-time: a finding is
  *  resolved/stale-marked, never superseded. */
 export declare const FindingSchema: z.ZodObject<{
+    visibility: z.ZodOptional<z.ZodObject<{
+        owner: z.ZodString;
+        readers: z.ZodArray<z.ZodString>;
+        writers: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     id: z.ZodString;
     title: z.ZodString;
     observation: z.ZodDefault<z.ZodString>;
@@ -538,8 +558,8 @@ export declare const FindingSchema: z.ZodObject<{
         critical: "critical";
     }>>;
     triage: z.ZodDefault<z.ZodEnum<{
-        open: "open";
         stale: "stale";
+        open: "open";
         "accepted-risk": "accepted-risk";
         scheduled: "scheduled";
         resolved: "resolved";
@@ -590,7 +610,7 @@ export declare function assertLandscapeDriftCandidate(value: unknown): asserts v
 /** Convert one valid external observation into advisory Hunch memory, never graph authority. */
 export declare function landscapeDriftCandidateFinding(value: unknown): Finding;
 /** The entity collections, keyed by their on-disk directory name. */
-export declare const ENTITY_KINDS: readonly ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings", "receipts", "commitments", "derived", "entities", "relationships"];
+export declare const ENTITY_KINDS: readonly ["components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings", "receipts", "commitments", "derived", "entities", "relationships", "conventions"];
 export type EntityKind = (typeof ENTITY_KINDS)[number];
 export declare const SCHEMAS: {
     readonly components: z.ZodObject<{
@@ -753,6 +773,11 @@ export declare const SCHEMAS: {
         last_changed: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>;
     readonly decisions: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         title: z.ZodString;
         topic: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -823,6 +848,11 @@ export declare const SCHEMAS: {
         date: z.ZodString;
     }, z.core.$strip>;
     readonly bugs: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         title: z.ZodString;
         symptom: z.ZodDefault<z.ZodString>;
@@ -857,6 +887,11 @@ export declare const SCHEMAS: {
         }, z.core.$strip>;
     }, z.core.$strip>;
     readonly constraints: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         type: z.ZodDefault<z.ZodEnum<{
             security: "security";
@@ -919,6 +954,11 @@ export declare const SCHEMAS: {
         date: z.ZodString;
     }, z.core.$strip>;
     readonly findings: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         id: z.ZodString;
         title: z.ZodString;
         observation: z.ZodDefault<z.ZodString>;
@@ -931,8 +971,8 @@ export declare const SCHEMAS: {
             critical: "critical";
         }>>;
         triage: z.ZodDefault<z.ZodEnum<{
-            open: "open";
             stale: "stale";
+            open: "open";
             "accepted-risk": "accepted-risk";
             scheduled: "scheduled";
             resolved: "resolved";
@@ -950,7 +990,76 @@ export declare const SCHEMAS: {
             last_verified: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
     }, z.core.$strip>;
+    readonly conventions: z.ZodObject<{
+        schema: z.ZodLiteral<"nuryel.convention/1">;
+        id: z.ZodString;
+        scope: z.ZodObject<{
+            kind: z.ZodEnum<{
+                repository: "repository";
+                organization: "organization";
+                team: "team";
+                user: "user";
+            }>;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        key: z.ZodString;
+        value: z.ZodString;
+        status: z.ZodEnum<{
+            stale: "stale";
+            proposed: "proposed";
+            accepted: "accepted";
+            withdrawn: "withdrawn";
+        }>;
+        sources: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"record">;
+            id: z.ZodString;
+            record_hash: z.ZodString;
+            scope: z.ZodOptional<z.ZodObject<{
+                kind: z.ZodEnum<{
+                    repository: "repository";
+                    organization: "organization";
+                    team: "team";
+                    user: "user";
+                }>;
+                id: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"external">;
+            ref: z.ZodObject<{
+                system: z.ZodString;
+                object_type: z.ZodString;
+                object_key: z.ZodString;
+                version: z.ZodOptional<z.ZodString>;
+                content_hash: z.ZodOptional<z.ZodString>;
+                observed_at: z.ZodString;
+                locator: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"schema">;
+            name: z.ZodString;
+            fingerprint: z.ZodString;
+        }, z.core.$strict>], "kind">>;
+        valid_from: z.ZodString;
+        valid_to: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        review_by: z.ZodString;
+        provenance: z.ZodObject<{
+            source: z.ZodString;
+            confidence: z.ZodNumber;
+            evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            last_verified: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
     readonly receipts: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.receipt/1">;
         id: z.ZodString;
         scope: z.ZodObject<{
@@ -1023,6 +1132,11 @@ export declare const SCHEMAS: {
         }, z.core.$strip>;
     }, z.core.$strict>;
     readonly commitments: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.commitment/1">;
         id: z.ZodString;
         scope: z.ZodObject<{
@@ -1065,6 +1179,11 @@ export declare const SCHEMAS: {
         }, z.core.$strip>;
     }, z.core.$strict>;
     readonly derived: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.derived/1">;
         id: z.ZodString;
         scope: z.ZodObject<{
@@ -1108,6 +1227,18 @@ export declare const SCHEMAS: {
             name: z.ZodString;
             fingerprint: z.ZodString;
         }, z.core.$strict>], "kind">>;
+        field_provenance: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"json_pointer">;
+                path: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"text">;
+                start: z.ZodNumber;
+                end: z.ZodNumber;
+            }, z.core.$strict>], "kind">;
+            value_hash: z.ZodString;
+            dependency_hashes: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
         transform_version: z.ZodString;
         computed_at: z.ZodString;
         valid_to: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -1142,6 +1273,11 @@ export declare const SCHEMAS: {
         }, z.core.$strip>;
     }, z.core.$strict>;
     readonly entities: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.entity/1">;
         id: z.ZodString;
         kind: z.ZodString;
@@ -1181,6 +1317,11 @@ export declare const SCHEMAS: {
         updated_at: z.ZodString;
     }, z.core.$strict>;
     readonly relationships: z.ZodObject<{
+        visibility: z.ZodOptional<z.ZodObject<{
+            owner: z.ZodString;
+            readers: z.ZodArray<z.ZodString>;
+            writers: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
         schema: z.ZodLiteral<"nuryel.relationship/1">;
         id: z.ZodString;
         from: z.ZodString;
@@ -1228,6 +1369,7 @@ export type EntityFor = {
     constraints: Constraint;
     runbooks: Runbook;
     findings: Finding;
+    conventions: Convention;
     receipts: ActionReceipt;
     commitments: Commitment;
     derived: DerivedState;

package/dist/core/types.js

@@ -1,3 +1,4 @@
+import { RecordVisibilitySchema } from "./recordVisibility.js";
 /**
  * Core entity schema for the Project Hunch (DESIGN.md §3).
  *
@@ -9,7 +10,7 @@ import { z } from "zod";
 import { createHash } from "node:crypto";
 import { findingId, resourceId, resourceRelationshipId } from "./ids.js";
 import { ProvenanceSchema, SENSITIVE_METADATA_KEY, isCredentialFreeText } from "./provenance.js";
-import { ActionReceiptSchema, CommitmentSchema, DerivedStateSchema, ExternalEntitySchema, StateRelationshipSchema, } from "./stateRecords.js";
+import { ConventionSchema, ActionReceiptSchema, CommitmentSchema, DerivedStateSchema, ExternalEntitySchema, StateRelationshipSchema, } from "./stateRecords.js";
 // Provenance and the credential-free text check live in the leaf module ./provenance.js so
 // record schemas registered below can import them without a cycle; re-exported unchanged.
 export { ProvenanceSchema, isCredentialFreeText };
@@ -323,6 +324,7 @@ export const PremiseSchema = z.object({
     path: ["under"],
 });
 export const DecisionSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     id: z.string().describe("dec_*"),
     title: z.string(),
     // Decision-grounding anchor: the join key that relates a doc section, a decision,
@@ -372,6 +374,7 @@ export const BugLineageSchema = z.object({
 });
 /** A bug with root cause and lineage (introduced → fixed → recurred). */
 export const BugSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     id: z.string().describe("bug_*"),
     title: z.string(),
     symptom: z.string().default(""),
@@ -388,6 +391,7 @@ export const BugSchema = z.object({
 });
 /** An invariant the system must respect. */
 export const ConstraintSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     id: z.string().describe("con_*"),
     type: z.enum(["security", "performance", "correctness", "architecture", "compliance"]).default("correctness"),
     statement: z.string(),
@@ -448,6 +452,7 @@ export const RunbookSchema = z.object({
  *  never enters any block path. Lifecycle is `triage`, not valid-time: a finding is
  *  resolved/stale-marked, never superseded. */
 export const FindingSchema = z.object({
+    visibility: RecordVisibilitySchema.optional(),
     id: z.string().describe("fnd_*"),
     title: z.string(),
     observation: z.string().default("").describe("what was observed, in plain words"),
@@ -594,7 +599,7 @@ export function landscapeDriftCandidateFinding(value) {
 // loads exactly as before, and an older build ignores directories it does not know.
 export const ENTITY_KINDS = [
     "components", "resources", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings",
-    "receipts", "commitments", "derived", "entities", "relationships",
+    "receipts", "commitments", "derived", "entities", "relationships", "conventions",
 ];
 export const SCHEMAS = {
     components: ComponentSchema,
@@ -606,6 +611,7 @@ export const SCHEMAS = {
     constraints: ConstraintSchema,
     runbooks: RunbookSchema,
     findings: FindingSchema,
+    conventions: ConventionSchema,
     receipts: ActionReceiptSchema,
     commitments: CommitmentSchema,
     derived: DerivedStateSchema,

package/dist/extractors/git.js

@@ -1838,16 +1838,9 @@ export function isLinkedWorktree(cwd) {
     const own = gitSafe(["rev-parse", "--absolute-git-dir"], cwd);
     if (!common || !own)
         return false;
-    // realpath BOTH before comparing: `--absolute-git-dir` is symlink-resolved while
-    // gitCommonDir is not, so on macOS the main checkout would otherwise mismatch on
-    // /var vs /private/var and falsely read as "linked".
-    const norm = (p) => { try {
-        return realpathSync(p);
-    }
-    catch {
-        return resolve(p);
-    } };
-    return norm(own) !== norm(common);
+    // Git can spell the same directory differently: /var vs /private/var on
+    // macOS, or long vs 8.3/case variants on Windows. Compare physical identity.
+    return !sameFilesystemEntry(own, common);
 }
 /** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
  *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */

package/dist/mcp/server.js

@@ -1,3 +1,5 @@
+import { conventionSupplements } from '../core/conventionDelivery.js';
+import { fieldCitationText } from "../core/fieldProvenance.js";
 /**
  * MCP server — the structured two-way API into the Hunch (DESIGN.md §7 / App. A).
  * Exposes read tools (query/why/bug_lineage/check_constraints/get_dependents) and
@@ -1102,7 +1104,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             decisionCorpus: store.recs("decisions"),
             historical: !!asOf,
             profile: profile ?? "builder",
-            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding],
+            supplements: [...(dnaSupplement ? [dnaSupplement] : []), ...stateGrounding, ...(asOf ? [] : conventionSupplements(store.recs("conventions")))],
         };
         // Task-phrase input ("improve retrieval ranking") resolves no file/symbol and
         // used to return an empty brief while the graph held the answer — fall back to
@@ -1822,7 +1824,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     const r = (response.records ?? {})[ref.id] ?? {};
                     const g = (k) => { const v = r[k]; return typeof v === "string" ? v : v == null ? "" : JSON.stringify(v); };
                     if (ref.facet === "derived")
-                        return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}`;
+                        return `- ${label} derived ${ref.id} · computed ${g("computed_at")} · ${r.dependencies?.length ?? 0} dependencies\n    ${g("content").slice(0, 1200)}${fieldCitationText(r)}`;
                     if (ref.facet === "commitments")
                         return `- ${label} commitment ${ref.id} · ${g("status")} · due ${g("due")} · owner ${g("owner")}: ${g("title")}${r.closed_by ? ` · closed by ${g("closed_by")}` : ""}`;
                     if (ref.facet === "receipts") {
@@ -1858,7 +1860,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                             : sor.observed_truncated ? ['- More observations exist; read this subject with observed_page:{} in one partition, then follow next_cursor.'] : []),
                         ...(sor.invalidated_by.length ? [`- invalidated by: ${sor.invalidated_by.join(", ")}`] : [])].join("\n") || "(nothing on record for this subject)"
                     : "";
-                return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}`, response);
+                const conventionText = response.conventions ? '\n\nExplicit conventions (advisory; no scope takes precedence):\n' + response.conventions.items.map(item => {
+                    const record = response.records?.[item.ref.id];
+                    return `- ${item.ref.scope.kind}/${item.ref.scope.id} · ${item.key} · ${record?.status}/${item.currentness}${item.conflict ? ' · CONFLICT' : ''}: ${String(record?.value ?? '').slice(0, 300)} (${item.ref.id})`;
+                }).join('\n') + (response.conventions.truncated ? '\nMore conventions exist; this view is incomplete.' : '') : '';
+                return stateResult(`${response.receipt_id} · ${summary}${deniedNote}${stateText ? `\n\nState of record:\n${stateText}` : ""}\n\n${envelope.text}${conventionText}`, response);
             }
             catch (e) {
                 return stateRefusal(e);
@@ -1866,7 +1872,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         });
         server.registerTool("nuryel_write", {
             title: "nuryel.state/1 write — provenance + idempotency in, durability out",
-            description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version.",
+            description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version. With capability nuryel.field-provenance/1, a derived record may carry field_provenance: [{selector:{kind:json_pointer,path:/field} or {kind:text,start:0,end:10}, value_hash:stateHash(selected scalar or text), dependency_hashes:[stateHash(existing dependency)]}]. Text offsets count Unicode code points, end exclusive. Citations are writer-supplied traceability, not verified support; negotiate support in every shared reader before writing them. With nuryel.record-visibility/1, records may carry visibility:{owner:principal-id,readers:[ids],writers:[ids]}; the owner is implicit in both lists, and writers must be readers. Owner-only audience changes require expected_version, including supersession. Restricted records require a dedicated partition; local stdio principal assertions assume trusted callers.",
             inputSchema: { ...WriteRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
             outputSchema: WriteResultSchema.shape,
         }, async ({ cwd: _cwd, ...input }) => {

package/dist/serve/app.d.ts

@@ -27,6 +27,8 @@ export declare class HttpProblem extends Error {
     constructor(status: number, code: string, message: string, extra?: Record<string, unknown>);
 }
 export interface ServeOptions {
+    /** Required for key-bound credentials when supplying an in-memory configuration. */
+    authStateDir?: string;
     version?: string;
     /** Injectable for tests: how a partition's store is opened. */
     openStore?: (root: string) => HunchStore;

package/dist/serve/app.js

@@ -1,3 +1,6 @@
+import { resolve } from 'node:path';
+import { StateProofError, verifyStateProof } from './stateProof.js';
+import { STATE_PROOF_CAPABILITY } from '../core/stateProof.js';
 /**
  * `hunch serve` — the HTTP binding of nuryel.state/1, and the served product's partition host.
  *
@@ -21,11 +24,12 @@ import { hunchPaths } from "../core/paths.js";
 import { flushCapture } from "../integrations/sync.js";
 import { StateRefusal, capabilities, mergeReadResponses, readState, recordsState, stateHomeFor, subscribeState, writeState } from "../store/stateBinding.js";
 import { STATE_READ_VERSION, STATE_RECORDS_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadScopesSchema, ScopeSchema, scopePath } from "../core/stateContract.js";
-import { partitionFor, resolvePrincipal } from "./config.js";
+import { partitionFor, resolveCredential, readServeConfig } from "./config.js";
 import { WriteLockTimeout, withWriteLock } from "./writelock.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { captureState, captureBatchState } from "../store/stateCapture.js";
 import { STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION } from "../core/stateContract.js";
+import { operatorHtml, operatorCss, operatorJs } from "./operator.js";
 export const BODY_LIMIT_BYTES = 1024 * 1024;
 export const PROBLEM_TYPE = "https://www.hunchmemory.com/problems/nuryel.state/1/";
 export class HttpProblem extends Error {
@@ -46,16 +50,6 @@ const problem = (status, code, message, extra = {}) => new HttpProblem(status, c
 const REFUSAL_STATUS = {
     "outside-grants": 403, unsupported: 400, malformed: 400, identity: 422, conflict: 409, idempotency: 409, "no-partition-home": 404,
 };
-function bearerToken(req) {
-    const header = req.headers.authorization;
-    if (!header)
-        return undefined;
-    const trimmed = header.trim();
-    if (!/^bearer /i.test(trimmed))
-        return undefined;
-    const token = trimmed.slice("bearer ".length).trim();
-    return token || undefined;
-}
 async function readBody(req) {
     const declared = req.headers["content-length"];
     if (declared !== undefined) {
@@ -95,9 +89,11 @@ function parseScopeParam(value) {
 }
 export function createServeApp(config, opts = {}) {
     const version = opts.version ?? HUNCH_VERSION;
+    const configFile = config.file;
+    const authStateDir = opts.authStateDir ?? (configFile ? resolve(configFile + ".auth") : undefined);
     const stores = new Map();
-    const storeFor = (scope) => {
-        const partition = partitionFor(config, scope);
+    const storeFor = (scope, activeConfig) => {
+        const partition = partitionFor(activeConfig, scope);
         if (!partition)
             throw problem(404, "no-partition", `this server does not serve ${scopePath(scope)}`);
         let store = stores.get(partition.root);
@@ -128,19 +124,59 @@ export function createServeApp(config, opts = {}) {
     };
     const server = createServer(async (req, res) => {
         try {
+            let activeConfig;
+            try {
+                activeConfig = configFile ? readServeConfig(configFile) : config;
+            }
+            catch {
+                throw problem(503, 'configuration-unavailable', 'server configuration is unavailable; authentication is refused');
+            }
+            const requestStore = (scope) => storeFor(scope, activeConfig);
             const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            // Public shell only: all workspace data still uses the authenticated state routes below.
+            const asset = new Map([["/operator", [operatorHtml, "text/html"]], ["/operator/", [operatorHtml, "text/html"]], ["/operator.css", [operatorCss, "text/css"]], ["/operator.js", [operatorJs, "text/javascript"]]]).get(url.pathname);
+            if (asset && req.method === "GET") {
+                res.writeHead(200, { "content-type": `${asset[1]}; charset=utf-8`, "content-length": Buffer.byteLength(asset[0]), "cache-control": "no-store", "x-content-type-options": "nosniff", "referrer-policy": "no-referrer", "content-security-policy": "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'" });
+                return res.end(asset[0]);
+            }
             if (url.pathname === "/nuryel/v1/health" && req.method === "GET") {
-                return send(res, 200, { ok: true, version, protocol: "nuryel.state/1", partitions: config.partitions.map((p) => scopePath(p.scope)) });
+                return send(res, 200, { ok: true, version, protocol: "nuryel.state/1", partitions: activeConfig.partitions.map((p) => scopePath(p.scope)) });
+            }
+            const authorization = /^(Bearer|DPoP) ([^\s]+)$/i.exec(req.headers.authorization ?? '');
+            const credential = resolveCredential(activeConfig, authorization?.[2]);
+            if (!credential)
+                throw problem(401, 'unauthorized', 'valid credentials are required');
+            const countHeader = (name) => req.rawHeaders.filter((header, index) => index % 2 === 0 && header.toLowerCase() === name).length;
+            if (countHeader('authorization') !== 1 || countHeader('dpop') > 1)
+                throw problem(401, 'invalid_dpop_proof', 'ambiguous authentication headers');
+            if (credential.proof_key) {
+                if (authorization[1].toLowerCase() !== 'dpop')
+                    throw problem(401, 'invalid_dpop_proof', 'this credential requires DPoP proof; bearer fallback is disabled');
+                if (!activeConfig.public_origin || !authStateDir)
+                    throw problem(503, 'proof-state-unavailable', 'key-bound authentication requires a public origin and persistent proof state');
+                try {
+                    await verifyStateProof({ proof: typeof req.headers.dpop === 'string' ? req.headers.dpop : undefined, key: credential.proof_key, method: req.method ?? '', url: activeConfig.public_origin + url.pathname, token: authorization[2], stateDir: authStateDir });
+                }
+                catch (error) {
+                    if (error instanceof StateProofError) {
+                        res.setHeader('WWW-Authenticate', `DPoP error="${error.code}", algs="EdDSA"`);
+                        if (error.nonce)
+                            res.setHeader('DPoP-Nonce', error.nonce);
+                        throw problem(401, error.code, error.message);
+                    }
+                    throw problem(503, 'proof-state-unavailable', 'proof replay state is unavailable; authentication is refused');
+                }
             }
-            const principal = resolvePrincipal(config, bearerToken(req));
-            if (!principal)
-                throw problem(401, "unauthorized", "a valid bearer token is required");
+            else if (authorization[1].toLowerCase() !== 'bearer' || req.headers.dpop !== undefined)
+                throw problem(401, 'invalid_dpop_proof', 'credential is not bound to a proof key');
+            const principal = { id: credential.id, kind: credential.kind, grants: credential.grants, ...(credential.display ? { display: credential.display } : {}) };
             if (url.pathname === "/nuryel/v1/capabilities" && req.method === "GET") {
                 const scope = parseScopeParam(url.searchParams.get("scope")) ?? principal.grants[0];
                 if (!principal.grants.some((g) => scopePath(g) === scopePath(scope)))
                     throw problem(403, "outside-grants", `scope ${scopePath(scope)} is outside the principal's grants`);
-                const { store } = storeFor(scope);
-                return send(res, 200, { ...capabilities(store), principal: { id: principal.id, kind: principal.kind, grants: principal.grants } });
+                const { store } = requestStore(scope);
+                const offered = capabilities(store);
+                return send(res, 200, { ...offered, capabilities: [...offered.capabilities, STATE_PROOF_CAPABILITY], principal: { id: principal.id, kind: principal.kind, grants: principal.grants } });
             }
             if (req.method !== "POST")
                 throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}`);
@@ -148,13 +184,15 @@ export function createServeApp(config, opts = {}) {
             // The body never names the principal: the token did.
             delete body.principal;
             delete body.schema;
+            // Only authenticated grants select stores for cross-partition source visibility.
+            const accessOptions = { additionalStores: principal.grants.map(grant => requestStore(grant).store) };
             if (url.pathname === "/nuryel/v1/read") {
                 const scope = requireScope(principal, body);
                 if (body.observed_page !== undefined && body.scopes !== undefined)
                     throw problem(400, 'malformed', 'observation pages require a single partition without scopes');
-                const { store } = storeFor(scope);
+                const { store } = requestStore(scope);
                 if (body.scopes === undefined) {
-                    const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body });
+                    const { response, envelope } = readState(store, { schema: STATE_READ_VERSION, principal, ...body }, accessOptions);
                     return send(res, 200, { ...response, envelope });
                 }
                 // Union read. The primary `scope` was gated above as always; every extra scope is
@@ -170,46 +208,49 @@ export function createServeApp(config, opts = {}) {
                 for (const s of requested.data)
                     if (isGranted(s) && scopePath(s) !== scopePath(scope) && !others.has(scopePath(s)))
                         others.set(scopePath(s), s);
-                const primary = readState(store, { schema: STATE_READ_VERSION, principal, ...rest, scope });
-                const merged = mergeReadResponses(primary.response, [...others.values()].map((other) => readState(storeFor(other).store, { schema: STATE_READ_VERSION, principal, ...rest, scope: other }).response), ungranted);
+                const primary = readState(store, { schema: STATE_READ_VERSION, principal, ...rest, scope }, accessOptions);
+                const merged = mergeReadResponses(primary.response, [...others.values()].map((other) => readState(requestStore(other).store, { schema: STATE_READ_VERSION, principal, ...rest, scope: other }, accessOptions).response), ungranted);
                 return send(res, 200, { ...merged, envelope: primary.envelope });
             }
             if (url.pathname === "/nuryel/v1/write") {
                 const scope = requireScope(principal, body);
-                const { store, root } = storeFor(scope);
+                const { store, root } = requestStore(scope);
                 const { hunchDir } = stateHomeFor(store, scope);
                 const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, {
+                    ...accessOptions,
                     flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
                 }));
                 return send(res, result.outcome === "created" ? 201 : 200, result);
             }
             if (url.pathname === "/nuryel/v1/capture") {
                 const scope = requireScope(principal, body);
-                const { store, root } = storeFor(scope);
+                const { store, root } = requestStore(scope);
                 const { hunchDir } = stateHomeFor(store, scope);
                 const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, {
+                    ...accessOptions,
                     flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
                 }));
                 return send(res, result.outcome === "created" ? 201 : 200, result);
             }
             if (url.pathname === "/nuryel/v1/capture-batch") {
                 const scope = requireScope(principal, body);
-                const { store, root } = storeFor(scope);
+                const { store, root } = requestStore(scope);
                 const { hunchDir } = stateHomeFor(store, scope);
                 const result = await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, {
+                    ...accessOptions,
                     flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
                 }));
                 return send(res, 200, result);
             }
             if (url.pathname === "/nuryel/v1/subscribe") {
                 const scope = requireScope(principal, body);
-                const { store } = storeFor(scope);
-                return send(res, 200, subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }));
+                const { store } = requestStore(scope);
+                return send(res, 200, subscribeState(store, { schema: STATE_SUBSCRIBE_VERSION, principal, ...body }, accessOptions));
             }
             if (url.pathname === "/nuryel/v1/records") {
                 const scope = requireScope(principal, body);
-                const { store } = storeFor(scope);
-                return send(res, 200, recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }));
+                const { store } = requestStore(scope);
+                return send(res, 200, recordsState(store, { schema: STATE_RECORDS_VERSION, principal, ...body }, accessOptions));
             }
             throw problem(404, "not-found", `${url.pathname} is not a nuryel.state/1 route`);
         }