Implement durable typed journals, subscriptions, and Reader document connections

Add checked native journal/subscription bindings, managed-reference retention,
bounded history and backpressure, atomic delivery receipts, and fenced hosting.
Preserve source publication prediction and replica reconciliation; subscription
attachment, controls, and delivery remain authoritative in this initial version.

Connect independent manual/Gutenberg document producers to Reader bookshelves
through typed adapters. Add connection inspection, shared provider selection,
authoring documentation, and restart/rejection/fan-out integration coverage.

Verified compiler suite (287 passed, two existing skips), Nix runtime and
PostgreSQL qualification, five example assemblies, headless Reader integration,
Chromium Reader integration, resource pins, formatting, and lint.
No pinned workspace runtime was deployed.

test/execution-contracts.test.ts

@@ -51,10 +51,9 @@ test("portable contracts preserve exact selected operations and targets", () =>
   });
 });
 
-test("portable dependency diagnostics reject remote defaults, missing targets, and broad acquisition", () => {
+test("portable dependency diagnostics reject remote defaults and broad acquisition", () => {
   for (const [selection, execution, message] of [
     ["using [refresh.call]", "snapshot targets [browser]", "remote-only"],
-    ["using [label.get]", "snapshot targets [arduino]", "arduino"],
     ["", "snapshot targets [browser]", "select"],
     ["using [label.get, label.get]", "snapshot targets [browser]", "duplicates"],
     ["using [label.set]", "snapshot targets [browser]", "Unknown"],
@@ -65,6 +64,13 @@ test("portable dependency diagnostics reject remote defaults, missing targets, a
   }
 });
 
+test("package code targets may exceed a dependency's public minimum", () => {
+  const result = program("using [label.get]", "snapshot targets [arduino]");
+  assert.ok(result.ok, JSON.stringify(result.diagnostics));
+  // A workspace still has to provide the full installed closure before an
+  // operation can promise this target; package code alone is insufficient.
+});
+
 test("portable query getters and target declarations are checked", () => {
   assert.equal(data("remote").ok, false);
   assert.equal(data("transaction targets [browser]").ok, false);

test/execution-world.test.ts

@@ -16,11 +16,34 @@ import {
 } from "../src/execution-world/index.js";
 
 import { buildArtifactFixture as buildFixture } from "./artifact-fixture.js";
+import { compileKernelProgram } from "../src/execution-world/kernel.js";
 const resign = (implementation: ArtifactImplementation) => {
   const { contentDigest, ...body } = implementation;
   implementation.contentDigest = implementationDigest(body);
 };
 
+test("installed targets can exceed the public requirement without changing that contract", async () => {
+  const workspace = await loadReaderWorkspace((name, text) =>
+    name === "DocumentFactory.qx" ? text.replaceAll("targets [browser, server]", "targets [server]") : text,
+  );
+  const plan = compileExecutionPlan(workspace);
+  const factory = plan.definition.operations.find(
+    (op) => op.binding.kind === "package" && op.binding.exportId === "reader:create-document",
+  )!;
+  assert.deepEqual(factory.execution, { kind: "transaction", targets: ["server"] });
+  assert.deepEqual(factory.availableTargets, ["browser", "server"]);
+  const kernel = compileKernelProgram(plan) as { operations: { key: string; targets: string[] }[] };
+  assert.deepEqual(kernel.operations.find((op) => op.key === factory.key)!.targets, ["browser", "server"]);
+
+  const provider = workspace.packageImports
+    .flatMap((pkg) => pkg.exports)
+    .find((entry) => entry.id === "reader:create-document")!;
+  provider.execution = { kind: "transaction", targets: ["server"] };
+  const authoritative = compileExecutionPlan(workspace).definition.operations.find((op) => op.key === factory.key)!;
+  assert.deepEqual(authoritative.availableTargets, ["server"]);
+  assert.deepEqual(authoritative.execution, factory.execution);
+});
+
 test("reader execution plan closes selector storage and traversed interface dependencies", async () => {
   const workspace = await loadReaderWorkspace();
   const plan = compileExecutionPlan(workspace);

test/fixtures/events/event-handler.qx

@@ -0,0 +1,5 @@
+interface EventHandler<value Payload,value Parameters> id "interface:org.quixos.events:handler" revision "interface:org.quixos.events:handler@1" {
+  operation handle id "events:handle" : record {event:Payload;parameters:Parameters;} -> unit {
+    call id "events:handle:call" execution transaction targets [server];
+  }
+}

test/fixtures/events/event-stream-record.qx

@@ -0,0 +1,3 @@
+import interface EventStream;
+// Opt into the standard workspace journal conformance rule.
+interface EventStreamRecord<value Payload> id "interface:org.quixos.events:stream-record" revision "interface:org.quixos.events:stream-record@1" requires EventStream<Payload> {}

test/fixtures/events/event-stream.qx

@@ -0,0 +1,13 @@
+// Required server support; a checked installed implementation may additionally predict locally.
+interface EventStream<value Payload> id "interface:org.quixos.events:stream" revision "interface:org.quixos.events:stream@1" {
+  operation publish id "events:publish" : Payload -> record {publication:string;} {
+    call id "events:publish:call" execution transaction targets [server];
+  }
+  queryable value head id "events:head" : optional<uint64> {
+    get id "events:head:get" execution snapshot targets [server];
+  }
+  operation readPage id "events:read-page" : record {after:optional<string>;limit:uint32;}
+  -> record {entries:list<record {publication:string;position:uint64;payload:Payload;}>;next:optional<string>;asOfHead:optional<uint64>;} {
+    call id "events:read-page:call" execution snapshot targets [server];
+  }
+}

test/fixtures/events/event-subscription-record.qx

@@ -0,0 +1,2 @@
+import interface EventSubscription;
+interface EventSubscriptionRecord<value Payload,value Parameters> id "interface:org.quixos.events:subscription-record" revision "interface:org.quixos.events:subscription-record@1" requires EventSubscription<Payload,Parameters> {}

test/fixtures/events/event-subscription.qx

@@ -0,0 +1,18 @@
+import interface EventStream;
+import interface EventHandler;
+type StartPosition = variant id "org.quixos.events:start@1" {
+  future id "events:start:future" : unit;
+  retained id "events:start:retained" : unit;
+  afterCursor id "events:start:after" : string;
+};
+interface EventSubscription<value Payload,value Parameters> id "interface:org.quixos.events:subscription" revision "interface:org.quixos.events:subscription@1" {
+  operation attach id "events:attach" : record {source:interface-ref<EventStream<Payload>>;handler:interface-ref<EventHandler<Payload,Parameters>>;parameters:Parameters;start:StartPosition;} -> unit {
+    call id "events:attach:call" execution transaction targets [server];
+  }
+  queryable value status id "events:status" : record {status:string;generation:uint64;cursor:uint64;failure:optional<record {publication:string;code:string;message:string;}>;} {
+    get id "events:status:get" execution snapshot targets [server];
+  }
+  operation pause id "events:pause" : unit -> unit {call id "events:pause:call" execution transaction targets [server];}
+  operation resume id "events:resume" : unit -> unit {call id "events:resume:call" execution transaction targets [server];}
+  operation retire id "events:retire" : unit -> unit {call id "events:retire:call" execution transaction targets [server];}
+}

test/fixtures/events/rules.qx

@@ -0,0 +1,21 @@
+fragment {
+  import interface EventStream;
+  import interface EventHandler;
+  import interface EventSubscription;
+  import interface EventStreamRecord;
+  import interface EventSubscriptionRecord;
+  conform<value Payload> EventStreamRecord<Payload> as EventStream<Payload> id "events:standard-stream" {
+    private state Entries id "events:entries" on Self : Payload policy journal {"maxEntries":128,"maxBytes":1048576,"maxPublicationBytes":262144,"maxProtectedSubscriptions":32};
+    bind publish.call to journal Entries.publish;
+    bind head.get to journal Entries.head;
+    bind readPage.call to journal Entries.readPage;
+  }
+  conform<value Payload,value Parameters> EventSubscriptionRecord<Payload,Parameters> as EventSubscription<Payload,Parameters> id "events:standard-subscription" {
+    private state Delivery id "events:delivery" on Self : Parameters policy subscription(Payload);
+    bind attach.call to subscription Delivery.attach;
+    bind status.get to subscription Delivery.status;
+    bind pause.call to subscription Delivery.pause;
+    bind resume.call to subscription Delivery.resume;
+    bind retire.call to subscription Delivery.retire;
+  }
+}

test/generics.test.ts

@@ -603,3 +603,32 @@ test("prerequisites require explicit conformances and remain in the capability c
   applied.application!.arguments = [{ kind: "value", type: valueType.int64 }];
   assert.equal(compileWorkspaceRevision(forged).ok, false);
 });
+
+test("edge read targets honor declared interface prerequisites without inferring unrelated conformances", () => {
+  const interfaces = new Map();
+  for (const text of [
+    'interface Base id "base" revision "base@1" {}',
+    'import interface Base; interface Detailed id "detailed" revision "detailed@1" requires Base {}',
+    'import interface Base; interface Holder id "holder" revision "holder@1" {queryable relation item id "item" : optional-one interface Base {resolve id "item:resolve" execution snapshot targets [browser,server];}}',
+  ]) {
+    const parsed = compileCapabilityResourceSource(text, { source, environment: { interfaces } });
+    assert.ok(parsed.ok, JSON.stringify(parsed.diagnostics));
+    if (parsed.resource.kind !== "interface") throw Error("interface expected");
+    interfaces.set(parsed.resource.revision.displayName, parsed.resource.revision);
+  }
+  const assembly = `workspace W id "w" revision "w@1" commit "${source.commit}" {
+    import interface Base;import interface Detailed;import interface Holder;
+    atom Item id "item";atom Box id "box";
+    conform Item as Base id "item-base" {} conform Item as Detailed id "item-detailed" {}
+    conform Box as Holder id "box-holder" {
+      private edge ItemEdge id "items" {atom Self projection item id "item" optional-one;interface Detailed projection holders id "holders" many;}
+      bind item.resolve to edge ItemEdge.item.resolve;
+    }
+  }`;
+  const valid = compileCapabilitySource(assembly, "workspace.qx", { interfaces });
+  assert.ok(valid.ok, JSON.stringify(valid.diagnostics));
+  const unrelated = new Map(interfaces);
+  unrelated.set("Detailed", { ...interfaces.get("Detailed"), requiredInterfaces: [] });
+  const invalid = compileCapabilitySource(assembly, "workspace.qx", { interfaces: unrelated });
+  assert.equal(invalid.ok, false, "installed co-occurrence alone is not proof of a declared interface implication");
+});

test/journals.test.ts

@@ -0,0 +1,186 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { compileCapabilityResourceSource, compileCapabilitySource } from "../src/capability-language/parser.js";
+import { formatQx } from "../src/capability-language/source.js";
+import { compileExecutionPlan, compileKernelProgram } from "../src/execution-world/index.js";
+import type { InterfaceRevision } from "../src/capability-model/types.js";
+import { readFileSync } from "node:fs";
+
+const source = { repository: "https://example.test/journals", commit: "a".repeat(40) };
+
+test("standard event contracts instantiate generic native conformance rules", () => {
+  const interfaces = new Map<string, InterfaceRevision>();
+  for (const [name, slug] of [
+    ["EventStream", "event-stream"],
+    ["EventHandler", "event-handler"],
+    ["EventSubscription", "event-subscription"],
+    ["EventStreamRecord", "event-stream-record"],
+    ["EventSubscriptionRecord", "event-subscription-record"],
+  ]) {
+    const text = readFileSync(new URL(`../../test/fixtures/events/${slug}.qx`, import.meta.url), "utf8");
+    const result = compileCapabilityResourceSource(text, {
+      source,
+      environment: { interfaces, interfaceClosure: [...interfaces.values()] },
+    });
+    assert.ok(result.ok && result.resource.kind === "interface", JSON.stringify(result.diagnostics));
+    interfaces.set(name!, result.resource.revision);
+  }
+  const rules = readFileSync(new URL("../../test/fixtures/events/rules.qx", import.meta.url), "utf8")
+    .replace(/^fragment\s*\{/, "")
+    .replace(/}\s*$/, "");
+  const result = compileCapabilitySource(
+    `workspace Events id "events" revision "events@1" commit "${source.commit}" {
+    ${rules}
+    atom TextStream id "text-stream";
+    conform TextStream as EventStreamRecord<string> id "text-marker" {}
+    atom TextSubscription id "text-subscription";
+    conform TextSubscription as EventSubscriptionRecord<string,unit> id "text-subscription-marker" {}
+    atom NumberStream id "number-stream";
+    conform NumberStream as EventStreamRecord<uint32> id "number-marker" {}
+  }`,
+    "events.qx",
+    { interfaces, interfaceClosure: [...interfaces.values()] },
+  );
+  assert.ok(result.ok, JSON.stringify(result.diagnostics));
+  const kernel = compileKernelProgram(compileExecutionPlan(result.workspace)) as {
+    model: { owners: { slots: { policy: string }[] }[] };
+  };
+  assert.equal(
+    kernel.model.owners.flatMap((owner) => owner.slots).filter((slot) => slot.policy === "journal").length,
+    2,
+  );
+  assert.equal(
+    kernel.model.owners.flatMap((owner) => owner.slots).filter((slot) => slot.policy === "subscription").length,
+    1,
+  );
+});
+const contract = `external atom Document id "document";
+type Event = record { document: atom-ref<Document>; title: string; };
+interface Stream id "stream" revision "stream@1" {
+  operation publish id "publish" : Event -> record { publication: string; } {
+    call id "publish:call" execution transaction targets [server];
+  }
+  queryable value head id "head" : optional<uint64> { get id "head:get" execution snapshot targets [server]; }
+  operation readPage id "page" : record { after: optional<string>; limit: uint32; }
+    -> record { entries: list<record { publication: string; position: uint64; payload: Event; }>; next: optional<string>; asOfHead: optional<uint64>; } {
+    call id "page:call" execution snapshot targets [server];
+  }
+}`;
+const assembly = `workspace Journals id "journals" revision "journals@1" commit "${source.commit}" {
+  import interface Stream;
+  atom Document id "document";
+  atom Journal id "journal-object";
+  conform Journal as Stream id "journal-owner" {
+    private state Entries id "entries" on Journal : record { document: atom-ref<Document>; title: string; }
+      policy journal { "maxEntries": 32, "maxBytes": 65536, "maxPublicationBytes": 8192, "maxProtectedSubscriptions": 8 };
+    bind publish.call to journal Entries.publish;
+    bind head.get to journal Entries.head;
+    bind readPage.call to journal Entries.readPage;
+  }
+}`;
+function compile(text = assembly, iface = contract) {
+  const resource = compileCapabilityResourceSource(iface, { source });
+  assert.ok(resource.ok && resource.resource.kind === "interface", JSON.stringify(resource.diagnostics));
+  return compileCapabilitySource(formatQx(text), "journal.qx", {
+    interfaces: new Map([["Stream", resource.resource.revision]]),
+  });
+}
+test("journal bindings typecheck and lower managed reference pins", () => {
+  const result = compile();
+  assert.ok(result.ok, JSON.stringify(result.diagnostics));
+  const kernel = compileKernelProgram(compileExecutionPlan(result.workspace)) as {
+    model: { edges: unknown[]; owners: { slots: { policy: string; journal: { pins: unknown[] } }[] }[] };
+    operations: { binding: { kind: string; primitive: string } }[];
+  };
+  assert.equal(kernel.model.owners[0]!.slots[0]!.policy, "journal");
+  assert.equal(kernel.model.owners[0]!.slots[0]!.journal.pins.length, 1);
+  assert.equal(kernel.model.edges.length, 1);
+  assert.deepEqual(kernel.operations.map((op) => op.binding.primitive).sort(), ["head", "publish", "readPage"]);
+  assert.ok(kernel.operations.every((op) => op.binding.kind === "journal"));
+});
+test("journal declarations reject state access, bad bounds, seeding and signature substitution", () => {
+  for (const [ws, iface] of [
+    [assembly.replace("journal Entries.head", "state Entries.read"), contract],
+    [assembly.replace('"maxEntries": 32', '"maxEntries": 0'), contract],
+    [assembly.replace("bind publish.call", "initialize { seed to state Entries; }; bind publish.call"), contract],
+    [assembly, contract.replace("publication: string", "publication: uint32")],
+    [assembly, contract.replace("execution transaction", "execution snapshot")],
+  ]) {
+    const result = compile(ws, iface);
+    assert.equal(result.ok, false, `${ws}\n${iface}`);
+  }
+});
+
+test("subscription storage infers its typed handler and retains configuration references", () => {
+  const interfaces = new Map<string, InterfaceRevision>();
+  const resource = (name: string, text: string) => {
+    const result = compileCapabilityResourceSource(text, {
+      source,
+      environment: { interfaces, interfaceClosure: [...interfaces.values()] },
+    });
+    assert.ok(result.ok && result.resource.kind === "interface", JSON.stringify(result.diagnostics));
+    interfaces.set(name, result.resource.revision);
+  };
+  resource("Stream", contract);
+  resource(
+    "Receiver",
+    `external atom Document id "document";
+interface Receiver id "receiver" revision "receiver@1" {
+  operation receive id "receive" : record { event: record { document: atom-ref<Document>; title: string; }; parameters: string; } -> unit {
+    call id "receive:call" execution transaction targets [server];
+  }
+}`,
+  );
+  resource(
+    "Subscription",
+    `external atom Document id "document";
+import interface Stream;
+import interface Receiver;
+type Start = variant id "start" { future id "future" : unit; retained id "retained" : unit; afterCursor id "after" : string; };
+interface Subscription id "subscription" revision "subscription@1" {
+  operation attach id "attach" : record { source: interface-ref<Stream>; handler: interface-ref<Receiver>; parameters: string; start: Start; } -> unit {
+    call id "attach:call" execution transaction targets [server];
+  }
+  queryable value status id "status" : record { status: string; generation: uint64; cursor: uint64; failure: optional<record { publication: string; code: string; message: string; }>; } {
+    get id "status:get" execution snapshot targets [server];
+  }
+  operation retire id "retire" : unit -> unit { call id "retire:call" execution transaction targets [server]; }
+}`,
+  );
+  const ws = assembly
+    .replace(
+      "import interface Stream;",
+      "import interface Stream; import interface Receiver; import interface Subscription;",
+    )
+    .replace(
+      /\n}$/,
+      `
+  atom Delivery id "delivery";
+  conform Delivery as Subscription id "delivery-owner" {
+    private state DeliveryState id "delivery-state" on Delivery : string policy subscription(record { document: atom-ref<Document>; title: string; });
+    bind attach.call to subscription DeliveryState.attach;
+    bind status.get to subscription DeliveryState.status;
+    bind retire.call to subscription DeliveryState.retire;
+  }
+}`,
+    );
+  const result = compileCapabilitySource(formatQx(ws), "subscriptions.qx", {
+    interfaces,
+    interfaceClosure: [...interfaces.values()],
+  });
+  assert.ok(result.ok, JSON.stringify(result.diagnostics));
+  const kernel = compileKernelProgram(compileExecutionPlan(result.workspace)) as {
+    model: {
+      owners: { slots: { policy: string; subscription?: { operation: string; pins: unknown[]; active: unknown } }[] }[];
+    };
+  };
+  const slot = kernel.model.owners.flatMap((owner) => owner.slots).find((slot) => slot.policy === "subscription")!;
+  assert.equal(slot.subscription!.operation, "receive:call");
+  assert.equal(slot.subscription!.pins.length, 2);
+  assert.ok(slot.subscription!.active);
+  const bad = compileCapabilitySource(ws.replace("on Delivery : string", "on Delivery : uint32"), "bad.qx", {
+    interfaces,
+    interfaceClosure: [...interfaces.values()],
+  });
+  assert.equal(bad.ok, false, "remembered parameter type must agree with attachment and handler");
+});

test/reference-dependencies.test.ts

@@ -82,9 +82,15 @@ test("closed generic specialization preserves reference-selected interface ports
   );
 });
 
-test("portable input-selected reads require the dependency's declared target support", () => {
+test("portable input-selected reads use installed support beyond the public minimum", () => {
   const portable = pkg.replaceAll("targets [server]", "targets [browser, server]");
-  assert.equal(compile(portable).ok, false);
+  const optional = compile(portable);
+  assert.ok(optional.ok, JSON.stringify(optional.diagnostics));
+  const plan = compileExecutionPlan(optional.workspace);
+  assert.deepEqual(plan.definition.operations.find((op) => op.operationId === "peek:call")!.availableTargets, [
+    "browser",
+    "server",
+  ]);
   const result = compile(portable, workspace, iface.replaceAll("targets [server]", "targets [browser, server]"));
   assert.ok(result.ok, JSON.stringify(result.diagnostics));
 });