Implement workspace evolution, migrations, and runtime continuity

Enable evolution by default for source-backed workspaces. Add stable
conformance ownership, semantic-major review, candidate typechecking,
and durable fenced cutover with explicit migrations and forward recovery.

Independently supervise package runtimes so unchanged resource owners keep
their processes and connections across cutover. Add scoped invocation
authority, resource sessions, and typed callback rebinding.

Wire opaque object references through generated bindings and RPCs. Add
canonical relationship sets, keyed maps, and ordered lists with scoped
transactional mutations, revision checks, and inverse consistency. Support
planned cascade deletion, protection, tombstones, and lifecycle foundations.

Add journaled structural edits, package/function/migration scaffolding,
managed repository creation, and resumable bottom-up dependency pin
publication. Document lifetime boundaries, revision pinning, prototype
compatibility policy, commands, and deferred work.

Validate with 210 tests, user-systemd process/connection continuity,
generated-package TypeScript checks, and Nix host/protocol checks.
TTL handoff, physical reclamation, general multi-step migrations, and
root-systemd migration isolation acceptance remain deferred.

src/bindings.ts

@@ -3,14 +3,16 @@ import { ValueSchema, ObjectValueSchema, type Value } from "./camino/api_pb.js";
 import { derived, jsToProtoValue, liveValue, protoValueToJs,
   type RuntimeContext, type RuntimeHandler, type DerivedHandler } from "./index.js";
 
-declare const referenceBrand: unique symbol;
-export type QxObjectRef<Identity extends string> = string & { readonly [referenceBrand]: { readonly [K in Identity]: true } };
+export type { QxObjectRef } from "./references.js";
+import { assertReferenceFree, referenceToWire } from "./references.js";
 declare const watchBrand: unique symbol;
 export type QxWatchHandle = string & { readonly [watchBrand]: true };
 export type MessageBinding<T> = { encode(value: T): Value; decode(value: Value): T };
 export type BindingValue<B> = B extends MessageBinding<infer T> ? T : never;
 export type QxHandler<C, O> = (context: C) => O | Promise<O>;
 export type QxDerived<C, O> = { kind: "derived"; get: QxHandler<C, O> };
+export type QxSession<C> = {id: string; run<T>(work: (context: C) => Promise<T>): Promise<T>; close(): Promise<void>};
+export type QxContextLifecycle<C> = {signal?: AbortSignal; openSession?: () => Promise<QxSession<C>>};
 export const qxDerived = <C, O>(get: QxHandler<C, O>): QxDerived<C, O> => ({ kind: "derived", get });
 
 /** Versioned binding ABI. This mirrors the language-neutral value IR. */
@@ -41,7 +43,17 @@ export const decodeQxValue = (type: QxValueType, value: Value | undefined, messa
     if (value.kind.case !== "listValue") throw new Error("Expected QX list");
     return value.kind.value.values.map((entry) => decodeQxValue(type.value, entry, messages));
   }
-  if (type.kind === "message") return requireMessage(messages, type.descriptorId).decode(value);
+  if (type.kind === "message") {
+    assertReferenceFree(protoValueToJs(value));
+    const decoded = requireMessage(messages, type.descriptorId).decode(value);
+    assertReferenceFree(decoded);
+    return decoded;
+  }
+  if (type.kind === "object-ref") {
+    if (value.kind.case !== "refValue") throw new Error("Expected a declared RPC object reference");
+    return protoValueToJs(value);
+  }
+  if (value.kind.case === "refValue") throw new Error("Reference supplied to a non-reference value");
   if (type.kind === "scalar") {
     if (type.name === "int64" || type.name === "uint64") {
       if (value.kind.case !== "integerValue") throw new Error("Expected QX integer");
@@ -64,8 +76,13 @@ export const encodeQxValue = (type: QxValueType, value: any, messages: QxMessage
   if (type.kind === "builtin" && type.name === "unit") return jsToProtoValue(null);
   if (type.kind === "optional") return value === null ? jsToProtoValue(null) : encodeQxValue(type.value, value, messages);
   if (type.kind === "list") return jsToProtoValue(value.map((entry: unknown) => liveValue(encodeQxValue(type.value, entry, messages))));
-  if (type.kind === "message") return requireMessage(messages, type.descriptorId).encode(value);
-  if (type.kind === "object-ref") return jsToProtoValue({ $quixosRef: value });
+  if (type.kind === "object-ref") { referenceToWire(value); return jsToProtoValue(value); }
+  assertReferenceFree(value);
+  if (type.kind === "message") {
+    const encoded = requireMessage(messages, type.descriptorId).encode(value);
+    assertReferenceFree(protoValueToJs(encoded));
+    return encoded;
+  }
   return jsToProtoValue(value);
 };
 
@@ -88,7 +105,7 @@ const inputFields = (type: QxValueType, value: unknown, messages: QxMessages): R
 export const bindQxHandler = <C, O>(
   spec: QxHandlerSpec, handler: QxHandler<C, O> | QxDerived<C, O>, messages: QxMessages,
 ): RuntimeHandler | DerivedHandler => {
-  const execute = async (raw: RuntimeContext) => {
+  const bindContext = (raw: RuntimeContext): C => {
     const ports = Object.fromEntries(Object.entries(spec.ports).map(([name, port]) => {
       switch (port.kind) {
         case "state": {
@@ -100,7 +117,9 @@ export const bindQxHandler = <C, O>(
         }
         case "edge": {
           const edge = raw.edge(port.id);
-          return [name, Object.fromEntries(port.primitives.map((primitive) => [primitive, edge[primitive as "resolve" | "connect" | "disconnect"]]))];
+          return [name, {...Object.fromEntries(port.primitives.map((primitive) => [primitive, edge[primitive as "resolve" | "connect" | "disconnect"]])),
+            ...(port.primitives.includes("resolve") ? {collection: edge.collection} : {}),
+            ...(port.primitives.includes("resolve") && port.primitives.includes("connect") && port.primitives.includes("disconnect") ? {replace: edge.replace} : {})}];
         }
         case "interface": {
           const target = raw.interface(port.id);
@@ -112,8 +131,16 @@ export const bindQxHandler = <C, O>(
         case "constructor": return [name, { construct: (input: unknown) => raw.constructor(port.id).construct(inputFields(port.inputType, input, messages)) }];
       }
     }));
-    const context = { objectId: raw.objectId,
+    return { objectId: raw.objectId, signal: raw.signal,
+      ...(raw.openSession ? {openSession: async () => {
+        const session = await raw.openSession!();
+        return {id: session.id, close: () => session.close(),
+          run: <T>(work: (context: C) => Promise<T>) => session.run((next) => work(bindContext(next)))};
+      }} : {}),
       input: decodeQxValue(spec.inputType, inputValue(raw, spec.inputType), messages), ports } as C;
+  };
+  const execute = async (raw: RuntimeContext) => {
+    const context = bindContext(raw);
     const value = await (typeof handler === "function" ? handler(context) : handler.get(context));
     return liveValue(encodeQxValue(spec.eventType ?? spec.outputType, value, messages));
   };