@junghanacs/entwurf 0.45.0 → 0.51.0

package/pi/pi-durable/carrier/sessions.js

@@ -4,6 +4,55 @@ import { mkdir, readdir, realpath, stat } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
 import lockfile from "proper-lockfile";
 import { getAgentDir } from "entwurf-pi-dist:config.js";
+import { isSessionName } from "./session-name.js";
+
+/**
+ * An owner's end as the opener observed it (#157 B3): the storage outcome of the first actual close, and the
+ * lease outcome of its release.
+ */
+                           
+	                                                                   
+	                                                                 
+	                               
+	                        
+ 
+
+/** One admitted owner of a session directory, from before its native lease through its end. */
+                              
+	                                                                                                         
+	                              
+	                                     
+	                        
+	                                                           
+	                               
+	                                     
+	                                          
+	                                                                                       
+	                             
+ 
+
+/** What an owned open hands the fence once its directory is chosen, before its native lease. */
+                                 
+	                                                                           
+	                           
+	                                                    
+	                           
+	                                                     
+	                          
+	   
+	                                                                                                                
+	                                                                    
+	   
+	                         
+ 
+
+/**
+ * The owner fence every owned open takes before its native lease (#157 B3). Supplied by the host, never imported
+ * here; it admits this opener or refuses, and a refusal opens nothing.
+ */
+                               
+	                                                     
+ 
 
 /** One session directory holding `session.sqlite`, locked by this process. */
                                   
@@ -13,6 +62,8 @@ import { getAgentDir } from "entwurf-pi-dist:config.js";
 	            
 	                 
 	                         
+	                                                                      
+	                    
  
 
 /** One session of a directory as its files show it (#143): nothing in it is opened. */
@@ -27,8 +78,6 @@ import { getAgentDir } from "entwurf-pi-dist:config.js";
 	                       
  
 
-const SESSION_NAME = /^\d{13}-[0-9a-f-]{36}$/u;
-
 /** A path's stat, or undefined when nothing is there; any other failure is thrown, never read as absence. */
 async function statIfPresent(path        )                             {
 	try {
@@ -39,15 +88,17 @@ async function statIfPresent(path        )                             {
 	}
 }
 
-async function sessionRoot(cwdInput        )                                         {
+async function sessionRoot(cwdInput        )                                                          {
 	const cwd = await realpath(resolve(cwdInput));
+	// Read once: the root is joined from this value, and the fence is handed this same value as it came (#157 B3).
+	const agentDir = getAgentDir();
 	const root = join(
-		getAgentDir(),
+		agentDir,
 		"experimental",
 		"durable-sessions",
 		createHash("sha256").update(cwd).digest("hex").slice(0, 24),
 	);
-	return { cwd, root };
+	return { cwd, root, profile: agentDir };
 }
 
 /** The sessions of `cwd`, most recently written first. Reads names, file times and locks; creates nothing. */
@@ -62,7 +113,7 @@ export async function listSessions(cwdInput        )                          {
 	}
 	const sessions                 = [];
 	for (const entry of entries) {
-		if (!entry.isDirectory() || !SESSION_NAME.test(entry.name)) continue;
+		if (!entry.isDirectory() || !isSessionName(entry.name)) continue;
 		const directory = join(root, entry.name);
 		let lastWriteAt                    ;
 		for (const file of ["session.sqlite", "session.sqlite-wal"]) {
@@ -80,19 +131,23 @@ export async function listSessions(cwdInput        )                          {
 	return sessions.sort((a, b) => (b.lastWriteAt ?? b.createdAt) - (a.lastWriteAt ?? a.createdAt));
 }
 
-/** A new session for `cwd`, its newest one with `continueSession`, or the existing one named by `sessionId`. */
+/**
+ * A new session for `cwd`, its newest one with `continueSession`, or the existing one named by `sessionId`, admitted
+ * by `fence` before its native lease is taken.
+ */
 export async function selectSession(
+	fence              ,
 	cwdInput        ,
 	continueSession         ,
 	sessionId         ,
 )                           {
-	const { cwd, root } = await sessionRoot(cwdInput);
+	const { cwd, root, profile } = await sessionRoot(cwdInput);
 	await mkdir(root, { recursive: true });
 
 	let directory        ;
 	let created = false;
 	if (sessionId !== undefined) {
-		const chosen = SESSION_NAME.test(sessionId) ? join(root, sessionId) : undefined;
+		const chosen = isSessionName(sessionId) ? join(root, sessionId) : undefined;
 		if (chosen === undefined || !(await statIfPresent(chosen))?.isDirectory()) {
 			throw new Error(`No durable session ${sessionId} exists for ${cwd}`);
 		}
@@ -100,7 +155,7 @@ export async function selectSession(
 	} else if (continueSession) {
 		const entries = await readdir(root, { withFileTypes: true });
 		const newest = entries
-			.filter((entry) => entry.isDirectory() && SESSION_NAME.test(entry.name))
+			.filter((entry) => entry.isDirectory() && isSessionName(entry.name))
 			.map((entry) => entry.name)
 			.sort()
 			.at(-1);
@@ -112,15 +167,36 @@ export async function selectSession(
 		created = true;
 	}
 
-	let release                     ;
-	try {
-		// A lock left by a crashed process goes stale after 10 s; wait that long before giving up.
-		release = await lockfile.lock(directory, {
-			realpath: false,
-			retries: { retries: 12, minTimeout: 1000, maxTimeout: 1000 },
+	// The owner fence admits this opener BEFORE the native lease, or refuses with nothing taken (#157 B3).
+	const ticket = await fence.admit({ directory, selectedN: basename(directory), created, profile });
+	// A lock left by a crashed process goes stale after 10 s; wait that long before giving up.
+	const lease = lockfile.lock(directory, {
+		realpath: false,
+		retries: { retries: 12, minTimeout: 1000, maxTimeout: 1000 },
+	});
+	const release = await lease.catch(async (error) => {
+		const refused = new Error(`Session is already open in another process: ${directory}`, { cause: error });
+		// No acquisition was observed: this owner ends with nothing opened and no lease held.
+		await ticket.endUnleased().catch((fenceError) => {
+			throw new AggregateError([refused, fenceError], `${refused.message}; its owner end was not recorded`);
 		});
-	} catch (error) {
-		throw new Error(`Session is already open in another process: ${directory}`, { cause: error });
-	}
-	return { id: basename(directory), directory, database: join(directory, "session.sqlite"), cwd, created, release };
+		throw refused;
+	});
+	// Apart from the lease's own failure: the lease IS held here, so a failed checkpoint is never recorded as an
+	// acquire failure. The open fails and releases the lease; the claim stays fenced under this live owner.
+	await ticket.leased().catch(async (error) => {
+		await release().catch((releaseError) => {
+			throw new AggregateError([error, releaseError], `lease checkpoint and release both failed: ${directory}`);
+		});
+		throw error;
+	});
+	return {
+		id: basename(directory),
+		directory,
+		database: join(directory, "session.sqlite"),
+		cwd,
+		created,
+		release,
+		ticket,
+	};
 }

package/pi/pi-durable/carrier/subagent.js

@@ -1,5 +1,5 @@
                                                      
-import {                        Type } from "@earendil-works/pi-ai";
+                                                              
 import {
 	AssistantEntry,
 	configure,
@@ -10,6 +10,7 @@ import {
 	                      
 	                         
 } from "@earendil-works/pi-durable";
+import { obj, str } from "@earendil-works/pi-schema";
 
 async function answerText(api                  , answer         , context         )                  {
 	const entry = await api.commit((tx) => tx.entry(AssistantEntry, answer), context);
@@ -29,7 +30,9 @@ export const Subagent            = defineExtension({
 			name: "subagent",
 			description:
 				"Delegate a self-contained task to a subagent with the same tools and get its answer back. Give it everything it needs to know; it does not see this conversation.",
-			parameters: Type.Object({ task: Type.String({ description: "What the subagent should do" }) }),
+			// pi-ai 1.5 no longer exports TypeBox's `Type`; pi-schema builds the same JSON Schema. `open` keeps the input
+			// as open as the TypeBox object was, since `obj()` alone closes it (SDK 1.5's own tools do the same, #155).
+			parameters: obj({ task: str({ description: "What the subagent should do" }) }, { open: true }),
 			// A rerun after a crash finds the child it created and the submission it made.
 			replay: "safe",
 			execute: async (args, api, context) => {

package/pi/pi-durable/carrier/tui.js

@@ -6,6 +6,7 @@
 	          
 	          
 	              
+	               
 	           
                                     
 import {
@@ -176,8 +177,9 @@ class CompactionComponent extends Box {
  
 
 /**
- * The lines above the editor: first what stays true for as long as it is true, the session's failure and the
- * compaction failure a conversation keeps until a compaction produces a summary, then the latest notices.
+ * The lines above the editor: first what stays true for as long as it is true, the session's failure, the
+ * compaction failure a conversation keeps until a compaction produces a summary, the run that ended without an
+ * answer until another run starts, and a view that stopped updating; then the latest notices.
  */
 export function durableNotices(view             )                                               {
 	const lines                                      = [];
@@ -188,9 +190,22 @@ export function durableNotices(view             )
 			message: `Session failed${cause}. It takes no more input, and a tool still running may take a while to stop. Close this session, then reopen it with --continue.`,
 		});
 	}
-	const compaction = ((view.conversation.docs["pi.live"] ?? {})             ).compactionFailure;
+	const live = (view.conversation.docs["pi.live"] ?? {})             ;
+	const compaction = live.compactionFailure;
 	if (compaction !== undefined) {
-		lines.push({ level: "error", message: `Compaction failed (${compaction.reason}): ${compaction.error}` });
+		lines.push({ level: "error", message: `Compaction failed (${compaction.trigger}): ${compaction.error}` });
+	}
+	// SDK 1.5 keeps why the newest run ended without an answer. An aborted run is the user's own stop, as before:
+	// the answer it cut off already says so.
+	const run = live.runFailure;
+	if (run !== undefined && run.reason !== "aborted") {
+		const detail = run.detail === undefined ? "" : ` (${run.detail})`;
+		lines.push({ level: "error", message: `No answer: ${run.reason}${detail}` });
+	}
+	for (const [part, error] of Object.entries(view.stalled ?? {})) {
+		if (error === undefined) continue;
+		const what = part === "tasks" ? "The task panel" : "The conversation";
+		lines.push({ level: "error", message: `${what} stopped updating: ${error}` });
 	}
 	return [...lines, ...view.notices.slice(-4)];
 }
@@ -289,7 +304,8 @@ class DurableTui {
 	         #summaries                        = [];
 	/** Tool output and summaries shown in full; toggled like pi. */
 	#expanded = false;
-	#renderedEntryIds           = [];
+	/** One key per transcript item on screen, in order (`keyOf`). */
+	#renderedKeys           = [];
 	#streaming                                       ;
 	#indicator                             ;
 	#statusText = "";
@@ -391,10 +407,11 @@ class DurableTui {
 
 	apply(view             )       {
 		const live = (view.conversation.docs["pi.live"] ?? {})             ;
-		this.#syncTranscript(view.conversation.entries);
+		// The active transcript, not the window: every entry of the active range, head marker first (#155 D1).
+		this.#syncTranscript(view.transcript.items);
 		const message = live.generation?.message                                ;
 		// A partial without its entry was dropped, for example by a retry: render the transcript again.
-		if (message === undefined && this.#streaming !== undefined) this.#rebuild(view.conversation.entries);
+		if (message === undefined && this.#streaming !== undefined) this.#rebuild(view.transcript.items);
 		if (message !== undefined) this.#syncStreaming(message);
 		for (const slot of live.tools ?? []) {
 			if (slot.status === "pending") continue;
@@ -476,8 +493,8 @@ class DurableTui {
 		} else if (generation?.deferred !== undefined) text = "Waiting for deferred response...";
 		else if (compaction !== undefined) {
 			text = compaction.retry
-				? `Retrying ${compaction.reason} compaction (attempt ${compaction.attempt + 1})...`
-				: `Compacting (${compaction.reason})...`;
+				? `Retrying ${compaction.trigger} compaction (attempt ${compaction.attempt + 1})...`
+				: `Compacting (${compaction.trigger})...`;
 		} else if (runningTool !== undefined) text = `Running ${runningTool.name}... (esc to abort)`;
 		else if (live.run !== undefined) text = "Working... (esc to abort)";
 		if (text === this.#statusText) return;
@@ -502,7 +519,7 @@ class DurableTui {
 			view.models.find((model) => model.provider === agent.model?.provider && model.modelId === agent.model.modelId)
 				?.contextWindow ?? 0;
 		if (contextWindow > 0) {
-			const tokens = contextTokens(view.conversation.entries);
+			const tokens = contextTokens(entriesOf(view.transcript.items));
 			const percent = tokens === undefined ? undefined : (tokens / contextWindow) * 100;
 			const text = `${percent === undefined ? "?" : percent.toFixed(1)}%/${formatTokens(contextWindow)}`;
 			stats.push(percent !== undefined && percent > 90 ? theme.fg("error", text) : text);
@@ -519,28 +536,38 @@ class DurableTui {
 		);
 	}
 
-	#syncTranscript(entries                        )       {
-		// Compaction and resets replace the head of the active transcript.
-		if (this.#renderedEntryIds.some((id, index) => entries[index]?.id !== id)) this.#rebuild(entries);
-		for (const entry of entries.slice(this.#renderedEntryIds.length)) {
-			this.#addEntry(entry);
-			this.#renderedEntryIds.push(entry.id);
+	#syncTranscript(items                           )       {
+		// The transcript grows at its end. A compaction or reset starts a new active range, its head marker first,
+		// which replaces what came before (#155 D1).
+		const keys = items.map(keyOf);
+		if (this.#renderedKeys.some((key, index) => keys[index] !== key)) this.#rebuild(items);
+		for (const item of items.slice(this.#renderedKeys.length)) {
+			this.#addItem(item);
+			this.#renderedKeys.push(keyOf(item));
 		}
 	}
 
-	#rebuild(entries                        )       {
+	#rebuild(items                           )       {
 		this.#chat.clear();
 		this.#discardTools();
 		this.#summaries.length = 0;
 		this.#rebuilt = true;
-		this.#renderedEntryIds = [];
+		this.#renderedKeys = [];
 		this.#streaming = undefined;
-		for (const entry of entries) {
-			this.#addEntry(entry);
-			this.#renderedEntryIds.push(entry.id);
+		for (const item of items) {
+			this.#addItem(item);
+			this.#renderedKeys.push(keyOf(item));
 		}
 	}
 
+	#addItem(item                )       {
+		if (item.kind === "entry") this.#addEntry(item.entry);
+		// The runtime's active transcript holds entries only; these two placeholders are the SDK item type's other kinds
+		// (#156 owns any load-more input).
+		else if (item.kind === "earlier") this.#addText("[earlier entries not shown]");
+		else this.#addText("[missing entries, loading...]");
+	}
+
 	#addEntry(entry             )       {
 		const message = entry.model?.[0];
 		if (entry.kind === "pi.user" && message?.role === "user") {
@@ -676,9 +703,20 @@ function totalUsage(state            )        {
 	return total;
 }
 
+/** The entries of transcript items, in ID order. */
+function entriesOf(items                           )                {
+	return items.flatMap((item) => (item.kind === "entry" ? [item.entry] : []));
+}
+
+/** What was rendered for an item stays valid while the same key stays in the same place. */
+function keyOf(item                )         {
+	if (item.kind === "entry") return `entry:${item.entry.id}`;
+	return item.kind === "gap" ? `gap:${item.after}:${item.upTo}` : "earlier";
+}
+
 /** Context size from the newest successful answer after the newest compaction; unknown before one. */
 function contextTokens(entries                        )                     {
-	// Kept entries follow the summary in the view but are older than it; only later answers measure the new context.
+	// Entries a summary keeps and those it replaced are older than it; only later answers measure the new context.
 	const compacted = Math.max(0, ...entries.filter((entry) => entry.kind === "pi.compaction").map((entry) => entry.id));
 	for (const entry of [...entries].reverse()) {
 		const message = entry.model?.[0];

package/pi/pi-durable/overlay/upstream-pin.json

@@ -55,7 +55,7 @@
 		}
 	},
 	"carrier": {
-		"comment": "files: the six app files bootstrap.mjs needs (main.ts is replaced by the bootstrap), each emitted from its owned `source`. distTargets: every pi-coding-agent internal the stripped files import, as paths under the published dist/; the emitter refuses a set that differs and the resolver answers no other.",
+		"comment": "files: the six app files bootstrap.mjs needs (main.ts is replaced by the bootstrap) and the import-free session-name grammar Entwurf owns beside them (#157 G3 B-L1, no upstream origin), each emitted from its owned `source`. distTargets: every pi-coding-agent internal the stripped files import, as paths under the published dist/; the emitter refuses a set that differs and the resolver answers no other.",
 		"emitter": {
 			"tool": "node:module.stripTypeScriptTypes",
 			"mode": "strip",
@@ -70,14 +70,14 @@
 			{
 				"name": "runtime.js",
 				"source": "pi/pi-durable/src/experimental/durable/runtime.ts",
-				"blob": "75d7bf2b4fdc36aa775f73f9d7f3de8659f19187",
-				"sha256": "725757156580ad2a2d170c790440763371bb8035052a0c6caae6af5159d4718f"
+				"blob": "00646b1b1fbd7e935fb3e66b7578a2befc01f3c8",
+				"sha256": "b47113364b7525abd3bf9286ecb0069f78ac96688b8a271bdbca3a54b9d864c5"
 			},
 			{
 				"name": "tui.js",
 				"source": "pi/pi-durable/src/experimental/durable/tui.ts",
-				"blob": "405600f6ba1558bf6bf22d144afdcf3f1295c282",
-				"sha256": "d4bf4e2861bde917e1dcdea6f063bdc3e101ab500107a9c5fab0e3ce97fb2c4a"
+				"blob": "4b5dd1876ceac8f51910bb11ed5f0024003f4f34",
+				"sha256": "7fefe490d9d462e6a91621901b82b767546926f4a9f4e88d585fe74b727a02c1"
 			},
 			{
 				"name": "harness-setup.js",
@@ -94,14 +94,20 @@
 			{
 				"name": "sessions.js",
 				"source": "pi/pi-durable/src/experimental/durable/sessions.ts",
-				"blob": "eed4b3ca51c6f5a3bab8106adaf0062f3f7d5b56",
-				"sha256": "668373feadabcf13bd4dd7431e5429b7d7376c47c367e4b15353c57cb8711892"
+				"blob": "f107238fefb63c95b29add5aa76fcbd9153c94db",
+				"sha256": "0ac7c919f2bf8a3b0e5dbd307045108a803b161f87298cd9fe440f239784c7ac"
 			},
 			{
 				"name": "subagent.js",
 				"source": "pi/pi-durable/src/experimental/durable/subagent.ts",
-				"blob": "3fa9aebbe93e82cfff436e7b9d4c9877e0ed0e27",
-				"sha256": "1cb2390b673a0d914117bc07708c39b004fb10e48b31436bf9d9d2b953a64220"
+				"blob": "e842d8a6b8dc55825d0381d803b6d6496b205c19",
+				"sha256": "c9931fabd60f5fbf75220e896a57e5c8b131b4936887bf6f9660d50d01709f3a"
+			},
+			{
+				"name": "session-name.js",
+				"source": "pi/pi-durable/src/experimental/durable/session-name.ts",
+				"blob": "c57c760ca3c14363f195ac9d9c2add984e4118d5",
+				"sha256": "9eadecfe9a48bba0d221370f4a236286e0d6f10d663b15ff4cb5975adee67018"
 			}
 		],
 		"distTargets": [
@@ -132,17 +138,18 @@
 		]
 	},
 	"sdk": {
-		"comment": "The published library set the carrier runs against, derived from the 1.4.0 declarations. members: the @earendil-works packages the carrier imports and every @earendil-works package those declare. direct: a third-party package a carrier file imports itself (sessions.ts: proper-lockfile, at the version pi-coding-agent 1.4.0 pins). Each is an exact production dependency in package.json. Since 1.3.0 the members' own edges are exact too (upstream #10865), and the installed physical edges are still what must equal these versions.",
+		"comment": "The published library set the carrier runs against, derived from the 1.5.0 declarations. members: the @earendil-works packages the carrier imports and every @earendil-works package those declare (1.5.0 adds pi-schema, declared by chord, pi-agent-core, pi-ai and pi-durable). direct: a third-party package a carrier file imports itself (sessions.ts: proper-lockfile, at the version pi-coding-agent 1.5.0 pins). Each is an exact production dependency in package.json. Since 1.3.0 the members' own edges are exact too (upstream #10865), and the installed physical edges are still what must equal these versions.",
 		"members": {
-			"@earendil-works/chord": "1.4.0",
-			"@earendil-works/pi-agent-core": "1.4.0",
-			"@earendil-works/pi-ai": "1.4.0",
-			"@earendil-works/pi-codemode": "1.4.0",
-			"@earendil-works/pi-coding-agent": "1.4.0",
-			"@earendil-works/pi-durable": "1.4.0",
-			"@earendil-works/pi-mcp": "1.4.0",
-			"@earendil-works/pi-telemetry": "1.4.0",
-			"@earendil-works/pi-tui": "1.4.0"
+			"@earendil-works/chord": "1.5.0",
+			"@earendil-works/pi-agent-core": "1.5.0",
+			"@earendil-works/pi-ai": "1.5.0",
+			"@earendil-works/pi-codemode": "1.5.0",
+			"@earendil-works/pi-coding-agent": "1.5.0",
+			"@earendil-works/pi-durable": "1.5.0",
+			"@earendil-works/pi-mcp": "1.5.0",
+			"@earendil-works/pi-schema": "1.5.0",
+			"@earendil-works/pi-telemetry": "1.5.0",
+			"@earendil-works/pi-tui": "1.5.0"
 		},
 		"direct": {
 			"proper-lockfile": "4.1.2"

package/pi-extensions/lib/entwurf-v2-contract-schema.ts

@@ -1,7 +1,7 @@
 /**
- * entwurf-v2-contract-schema — the pi-side TypeBox REPRESENTATION of the frozen
- * `entwurf_v2` contract. This module exists ONLY to carry the pi-ai TypeBox
- * schema builders (`StringEnum`, `Type`) out of the pi-free core
+ * entwurf-v2-contract-schema — the pi-side JSON Schema REPRESENTATION of the frozen
+ * `entwurf_v2` contract. This module exists ONLY to carry the pi schema builders
+ * (pi-ai's `StringEnum`, pi-schema's `obj`/`str`/…) out of the pi-free core
  * (`entwurf-v2-contract.ts`); the constants/types/decision logic live there.
  *
  * ⚠️ pi LANE ONLY — the MCP bridge (`mcp/entwurf-bridge/src/index.ts`) MUST NOT
@@ -11,18 +11,21 @@
  * the contract CONSTANTS + `resolveDispatch` (pi-free core), never these schemas.
  * Consumer: `check-entwurf-v2-contract` ONLY. This is a gate-side REPRESENTATION of the
  * frozen contract, not a shipped tool schema — measured 2026-07-27, nothing else in the
- * import graph reaches it. The two surfaces a model actually reads build their own:
- * `pi-extensions/entwurf-control.ts` (TypeBox `entwurfV2Parameters` + tool description) and
- * `mcp/entwurf-bridge/src/index.ts` (Zod). Change a model-facing description THERE; changing
- * it here reaches no model, and `check-entwurf-v2-surface` is what pins those two.
+ * import graph reaches it. The surface a model actually reads builds its own:
+ * `mcp/entwurf-bridge/src/index.ts` (Zod, descriptions from ENTWURF.json), which a pi citizen
+ * reaches through Pi's built-in MCP since the native pi tools were retired (2f7c883, Pi 0.99).
+ * Change a model-facing description THERE; changing it here reaches no model.
  *
- * StringEnum (typebox 1.x) inside Type.Object (typebox 0.34) — the same mix the
- * existing entwurf tools use. The logic types in the core are hand-written unions,
- * NOT `Static<>` inferences, so the 0.34/1.x widening caveat does not touch them;
- * `check-entwurf-v2-contract` keeps these schemas and the core types in lockstep.
+ * Pi SDK 1.5 (#155) removed pi-ai's TypeBox re-export (`Type`); its builders are now
+ * `@earendil-works/pi-schema`, which emits plain JSON Schema (obj() closed by default,
+ * opt() leaves a property out of `required`, lit() is `{const}`), and pi-ai's
+ * `StringEnum` still emits `{type:"string", enum}`. The logic types in the core are
+ * hand-written unions, NOT `Static<>` inferences; `check-entwurf-v2-contract` keeps
+ * these schemas and the core types in lockstep.
  */
 
-import { StringEnum, Type } from "@earendil-works/pi-ai";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { bool, lit, nul, obj, opt, type Properties, type Schema, str, union } from "@earendil-works/pi-schema";
 import {
 	ENTWURF_INTENTS,
 	ENTWURF_V2_ACTIONS,
@@ -34,36 +37,43 @@ import {
 } from "./entwurf-v2-contract.ts";
 import { SESSION_ID_RE } from "./session-id.js";
 
-export const EntwurfV2InputSchema = Type.Object(
-	{
-		// R2/F6 executable: the garden-id shape is enforced by pattern, not prose —
-		// a malformed/typo gid fails the schema (→ bad-target) and can never reach a
-		// spawn. SSOT regex = SESSION_ID_RE (pi-extensions/lib/session-id.js).
-		target: Type.String({
-			pattern: SESSION_ID_RE.source,
+/**
+ * The face the drift guard reads. pi-schema types a schema as `{[keyword]: unknown}`; obj() always emits
+ * `properties`, so this names that one keyword without asserting anything else about the shape.
+ */
+type ObjectSchema = Schema & { readonly properties: Readonly<Record<string, Schema>> };
+
+/** obj() — closed, so it emits `additionalProperties: false` — under the face above. */
+const closedObject = (properties: Properties): ObjectSchema => obj(properties) as ObjectSchema;
+
+export const EntwurfV2InputSchema = closedObject({
+	// R2/F6 executable: the garden-id shape is enforced by pattern, not prose —
+	// a malformed/typo gid fails the schema (→ bad-target) and can never reach a
+	// spawn. SSOT regex = SESSION_ID_RE (pi-extensions/lib/session-id.js).
+	target: str({
+		pattern: SESSION_ID_RE.source,
+		description:
+			"garden-id of an EXISTING citizen (pattern-enforced). Fresh sibling creation is out of scope on every current surface — there is no fallback verb that still spawns. A malformed/typo gid is bad-target, never a new spawn.",
+	}),
+	intent: StringEnum(ENTWURF_INTENTS, {
+		description:
+			"caller's declared outcome contract (F1). ONE member since the visible-first cut: fire-and-forget = ack only. The second, owned-outcome (caller owns completion), resumed a dormant citizen by launching a hidden background child and was withdrawn — a dormant citizen is currently unreachable by this verb.",
+	}),
+	mode: opt(
+		StringEnum(ENTWURF_V2_MODES, {
 			description:
-				"garden-id of an EXISTING citizen (pattern-enforced). Fresh sibling creation is out of scope on every current surface — there is no fallback verb that still spawns. A malformed/typo gid is bad-target, never a new spawn.",
+				"delivery mode — NOT the ownership axis (F1) nor liveness routing. steer (ask the receiver's steering queue) or follow_up (ask its follow-up queue). NEITHER is an interrupt: a busy receiver drains steering after each turn and follow-ups only when its inner loop ends, so a later steer overtakes every earlier follow_up and there is no order between the two. Both queues are volatile process memory — an abort drops what is in them. The receipt names which queue accepted the message (`queued-steer` / `queued-follow-up`); an idle receiver answers `sent`, meaning the turn was TRIGGERED, not that the model has seen the text. MEANINGLESS on the meta-mailbox transport (F-mailbox): a mailbox ack is enqueue+doorbell, not a turn injection, so steer/follow_up does not apply when the verdict transport is meta-mailbox.",
 		}),
-		intent: StringEnum(ENTWURF_INTENTS, {
-			description:
-				"caller's declared outcome contract (F1). ONE member since the visible-first cut: fire-and-forget = ack only. The second, owned-outcome (caller owns completion), resumed a dormant citizen by launching a hidden background child and was withdrawn — a dormant citizen is currently unreachable by this verb.",
+	),
+	wantsReply: opt(
+		bool({
+			description: "conversation etiquette only — NOT ownership; never triggers an auto-send (Q2).",
 		}),
-		mode: Type.Optional(
-			StringEnum(ENTWURF_V2_MODES, {
-				description:
-					"delivery mode — NOT the ownership axis (F1) nor liveness routing. steer (ask the receiver's steering queue) or follow_up (ask its follow-up queue). NEITHER is an interrupt: a busy receiver drains steering after each turn and follow-ups only when its inner loop ends, so a later steer overtakes every earlier follow_up and there is no order between the two. Both queues are volatile process memory — an abort drops what is in them. The receipt names which queue accepted the message (`queued-steer` / `queued-follow-up`); an idle receiver answers `sent`, meaning the turn was TRIGGERED, not that the model has seen the text. MEANINGLESS on the meta-mailbox transport (F-mailbox): a mailbox ack is enqueue+doorbell, not a turn injection, so steer/follow_up does not apply when the verdict transport is meta-mailbox.",
-			}),
-		),
-		wantsReply: Type.Optional(
-			Type.Boolean({
-				description: "conversation etiquette only — NOT ownership; never triggers an auto-send (Q2).",
-			}),
-		),
-		// `additionalProperties: false` — a frozen contract input is exact; an unknown
-		// key is a caller error, not silently ignored.
-	},
-	{ additionalProperties: false },
-);
+	),
+	// `additionalProperties: false` — a frozen contract input is exact; an unknown
+	// key is a caller error, not silently ignored. obj() is closed by default (it
+	// emits `additionalProperties: false` unless `open: true`).
+});
 
 // Receipt = a DISCRIMINATED union on `ok` (R3/F6) — NOT one flat object with
 // optionals. Each branch is EXACT (`additionalProperties: false`): without it,
@@ -72,35 +82,29 @@ export const EntwurfV2InputSchema = Type.Object(
 // With it, success carries action/transport/ownership and rejects a stray reason;
 // reject carries reason and rejects any allow facet — the branches are mutually
 // exclusive at the schema level, not merely by declared-property convention.
-export const EntwurfV2ReceiptSuccessSchema = Type.Object(
-	{
-		ok: Type.Literal(true),
-		action: StringEnum(ENTWURF_V2_ACTIONS),
-		transport: StringEnum(ENTWURF_V2_TRANSPORTS),
-		ownership: StringEnum(ENTWURF_V2_OWNERSHIPS),
-		observedLiveness: StringEnum(FACT_LIVENESSES, {
-			description: "the 4-value fact liveness the verdict was computed from (R1/R3).",
-		}),
-	},
-	{ additionalProperties: false },
-);
+export const EntwurfV2ReceiptSuccessSchema = closedObject({
+	ok: lit(true),
+	action: StringEnum(ENTWURF_V2_ACTIONS),
+	transport: StringEnum(ENTWURF_V2_TRANSPORTS),
+	ownership: StringEnum(ENTWURF_V2_OWNERSHIPS),
+	observedLiveness: StringEnum(FACT_LIVENESSES, {
+		description: "the 4-value fact liveness the verdict was computed from (R1/R3).",
+	}),
+});
 
-export const EntwurfV2ReceiptRejectSchema = Type.Object(
-	{
-		ok: Type.Literal(false),
-		reason: StringEnum(ENTWURF_V2_REJECT_REASONS),
-		// ？6: required-nullable, NOT optional — a reject branch ALWAYS carries the
-		// key, and it is `null` for the pre-probe rejects (PRE_PROBE_REJECT_REASONS)
-		// and a real FactLiveness otherwise. Optional would lose the "key always
-		// present, value may be null" shape and weaken the discriminated union; the
-		// reason-dependent null/non-null rule is enforced semantically (the gate's
-		// rejectObservedLivenessWellFormed fixture), not by this blanket union.
-		observedLiveness: Type.Union([StringEnum(FACT_LIVENESSES), Type.Null()], {
-			description:
-				"the 4-value fact liveness the reject was computed from (R1/R3); null for the pre-probe rejects (bad-target / target-locked / target-address-conflict) where no probe ran.",
-		}),
-	},
-	{ additionalProperties: false },
-);
+export const EntwurfV2ReceiptRejectSchema = closedObject({
+	ok: lit(false),
+	reason: StringEnum(ENTWURF_V2_REJECT_REASONS),
+	// ？6: required-nullable, NOT optional — a reject branch ALWAYS carries the
+	// key, and it is `null` for the pre-probe rejects (PRE_PROBE_REJECT_REASONS)
+	// and a real FactLiveness otherwise. Optional would lose the "key always
+	// present, value may be null" shape and weaken the discriminated union; the
+	// reason-dependent null/non-null rule is enforced semantically (the gate's
+	// rejectObservedLivenessWellFormed fixture), not by this blanket union.
+	observedLiveness: union([StringEnum(FACT_LIVENESSES), nul()], {
+		description:
+			"the 4-value fact liveness the reject was computed from (R1/R3); null for the pre-probe rejects (bad-target / target-locked / target-address-conflict) where no probe ran.",
+	}),
+});
 
-export const EntwurfV2ReceiptSchema = Type.Union([EntwurfV2ReceiptSuccessSchema, EntwurfV2ReceiptRejectSchema]);
+export const EntwurfV2ReceiptSchema = union([EntwurfV2ReceiptSuccessSchema, EntwurfV2ReceiptRejectSchema]);