@astrosheep/square 0.3.85 → 0.3.87

package/dist/artifact.d.ts

@@ -1,7 +1,10 @@
 import { DatabaseSync } from 'node:sqlite';
 import { type BuildOptions } from './model.js';
-import type { SquareArtifactPort } from './ports.js';
+import type { SquareResourceOwner, SquareArtifactPort } from './ports.js';
 import { type SquareState } from './square-sqlite.js';
+/** Explicit-lifetime holder of one reused artifact connection. Request cancellation
+ * never becomes the shared connection's lifetime; close drains the owner once. */
+export declare function createSquareResourceOwner(): SquareResourceOwner;
 /** All build paths share configuration validation and lazy guide preparation. */
 export declare function prepareSquareBuild(options: Omit<BuildOptions, 'force'>, snippet: string): SquareState;
 /** File build owns publication and CLI conflict semantics, not host resources. */
@@ -32,4 +35,6 @@ export declare function writeSquareFile(location: string, state: SquareState, si
 export declare function readSquareSnapshot(location: string, signal?: AbortSignal): Promise<SquareSnapshot>;
 export declare function readSquareRevision(location: string, signal?: AbortSignal): Promise<number>;
 export declare function observeSquareRevision(location: string): Promise<import('./file-changes.js').VersionObserver<number | null>>;
+export declare function readSquareDeliveryRevision(location: string, signal?: AbortSignal): Promise<number>;
+export declare function observeSquareDeliveryRevision(location: string): Promise<import('./file-changes.js').VersionObserver<number | null>>;
 export declare function diagnoseSquareFile(location: string): Promise<DiagnoseResult>;

package/dist/artifact.js

@@ -10,6 +10,33 @@ import { canonicalPath } from './canonical-path.js';
 import { InternalSquareError, SquareError } from './model.js';
 import { wrapSquareWrite } from './square-domain.js';
 import { APPLICATION_ID, CURRENT_USER_VERSION, createSqliteDriver, initializeSqlite, exportSqliteState, inspectSqlite, invalidArtifact, validateSqliteHeader, emptyRuntimeState } from './square-sqlite.js';
+/** Explicit-lifetime holder of one reused artifact connection. Request cancellation
+ * never becomes the shared connection's lifetime; close drains the owner once. */
+export function createSquareResourceOwner() {
+    let held;
+    let closed = false;
+    return {
+        artifact(location) {
+            if (closed)
+                throw new SquareError('unavailable', 'Square resource owner is closed');
+            const key = path.resolve(location);
+            if (held === undefined)
+                held = { location: key, artifact: createArtifactPort(key) };
+            if (held.location !== key)
+                throw new SquareError('unavailable', `Square resource owner already holds ${held.location}; it cannot also open ${key}`);
+            return held.artifact;
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            const artifact = held?.artifact;
+            held = undefined;
+            if (artifact !== undefined)
+                await artifact.close();
+        },
+    };
+}
 const guideContents = new Map();
 function readGuide(name) {
     if (!['participant', 'architect', 'brainstorm'].includes(name))
@@ -40,7 +67,7 @@ export function prepareSquareBuild(options, snippet) {
         hardCap: options.hardCap ?? null,
         ...(options.throttlePerMinute === undefined ? {} : { throttlePerMinute: options.throttlePerMinute }),
         preamble: normalizedLines(snippet), warmup: normalizedLines(guides.join('\n\n')),
-        acts: [], routes: [], runtime: emptyRuntimeState(),
+        acts: [], runtime: emptyRuntimeState(),
     };
 }
 /** File build owns publication and CLI conflict semantics, not host resources. */
@@ -93,9 +120,10 @@ const readMethods = [
     'header', 'participant', 'roster', 'attention', 'incomingAttention', 'hold',
     'activity', 'activityHeads', 'activities', 'activityCount', 'contextIndexes', 'sayOrdinals', 'recentSayTimes',
     'audience', 'directed', 'directedAt', 'directedCount', 'pendingAudience',
-    'receipt', 'receiptFacts', 'receiptAssignments', 'lease', 'routes', 'participantCounts',
+    'receipt', 'receiptFacts', 'receiptAssignments', 'lease', 'participantCounts', 'seat', 'seatsForBody', 'completedSeatsForBody',
+    'deliveryEvidence', 'deliveryByToken', 'cancelledThrough',
 ];
-const writeMethods = ['applyLanding', 'markSeen', 'putLease', 'removeLease', 'replaceRoutes'];
+const writeMethods = ['applyLanding', 'markSeen', 'putLease', 'removeLease', 'storeSeat', 'removeSeat', 'updateWakeAddress', 'cancelThrough', 'claimDelivery', 'prepareDelivery', 'completeDelivery', 'observeNativeDelivery'];
 /** One connection, ordered operations, guarded synchronous transaction capabilities. */
 export function createArtifactPort(location, initial, externalSignal) {
     let database;
@@ -146,7 +174,7 @@ export function createArtifactPort(location, initial, externalSignal) {
         tail = result.then(() => undefined, () => undefined);
         return result;
     }
-    async function transaction(callback, write, signal) {
+    async function transaction(callback, write, signal, authority) {
         const db = await connection(signal);
         return inSqliteTransaction(db, write, () => validate(db), (header) => {
             const driver = createSqliteDriver(db), version = header.revision;
@@ -170,12 +198,15 @@ export function createArtifactPort(location, initial, externalSignal) {
             }
             const reads = Object.fromEntries(readMethods.map(name => [name, guard(driver[name])]));
             const writes = Object.fromEntries(writeMethods.map(name => [name, guard(driver[name])]));
-            const facts = write ? wrapSquareWrite(reads, writes) : reads;
+            const gate = write ? wrapSquareWrite(reads, writes, authority) : undefined;
+            const facts = gate?.facts ?? reads;
             let value;
             inCallback = true;
             try {
                 value = callback(facts);
                 synchronous(value);
+                if (!failed)
+                    gate?.complete();
             }
             finally {
                 inCallback = false;
@@ -184,13 +215,14 @@ export function createArtifactPort(location, initial, externalSignal) {
             if (failed)
                 throw failure;
             const changed = write && driver.changed;
-            if (changed) {
+            const deliveryChanged = write && driver.deliveryChanged;
+            if (changed || deliveryChanged) {
                 if (version === Number.MAX_SAFE_INTEGER)
                     throw invalidArtifact('revision cannot advance beyond the safe integer limit.');
-                db.prepare('UPDATE square_meta SET revision=? WHERE id=1').run(version + 1);
+                db.prepare('UPDATE square_meta SET revision=revision+?, delivery_revision=delivery_revision+? WHERE id=1').run(Number(changed), Number(deliveryChanged));
             }
             return {
-                value, version: version + Number(changed), changed
+                value, version: version + Number(changed), changed, deliveryChanged
             };
         }, signal);
     }
@@ -203,8 +235,29 @@ export function createArtifactPort(location, initial, externalSignal) {
             const { value, version } = await transaction(select, false, s);
             return { value, version };
         }, signal),
-        transact: (change, signal) => queue(s => transaction(change, true, s), signal),
+        transactAs: (authority, change, signal) => queue(s => transaction(change, true, s, authority), signal),
         revision,
+        async deliveryRevision(signal) {
+            return queue(async (s) => {
+                const db = await connection(s);
+                return inSqliteTransaction(db, false, () => validate(db), (header) => header.deliveryRevision, s);
+            }, signal);
+        },
+        async claimDelivery(input, signal) {
+            return (await this.transactAs({ kind: 'participant', seat: input.seat }, (facts) => facts.claimDelivery(input), signal)).value;
+        },
+        async prepareDelivery(input, signal) {
+            return (await this.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.prepareDelivery(input), signal)).value;
+        },
+        async completeDelivery(input, signal) {
+            return (await this.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.completeDelivery(input), signal)).value;
+        },
+        async cancelDeliveries(seat, through, signal) {
+            return (await this.transactAs({ kind: 'participant', seat }, facts => {
+                const boundary = through ?? facts.header().lastActIndex;
+                return boundary < 0 ? false : facts.cancelThrough(seat, boundary);
+            }, signal)).value;
+        },
         async changed(since, timeout, signal) {
             if (inCallback)
                 throw new TypeError('Square artifact operations cannot nest inside a callback.');
@@ -321,7 +374,7 @@ export async function writeSquareFile(location, state, signal) {
             const revision = createSqliteDriver(db).header().revision;
             if (revision === Number.MAX_SAFE_INTEGER)
                 throw invalidArtifact('revision cannot advance beyond the safe integer limit.');
-            for (const table of ['landed_audience', 'attention', 'participants', 'routes', 'catch_leases', 'receipts', 'activities', 'square_meta'])
+            for (const table of ['landed_audience', 'attention', 'participants', 'delivery_cancellations', 'delivery_evidence', 'seats', 'catch_leases', 'receipts', 'activities', 'square_meta'])
                 db.exec(`DROP TABLE ${table}`);
             initializeSqlite(db, state, revision + 1);
         }, signal);
@@ -362,6 +415,22 @@ export function observeSquareRevision(location) {
         }
     });
 }
+export function readSquareDeliveryRevision(location, signal) {
+    return inspectFile(location, db => createSqliteDriver(db).header().deliveryRevision, signal);
+}
+export function observeSquareDeliveryRevision(location) {
+    return observeFileVersion(location, 'square-delivery-revision', async (file, signal) => {
+        try {
+            return await readSquareDeliveryRevision(file, signal);
+        }
+        catch (error) {
+            abort(signal);
+            if (error instanceof InternalSquareError && error.code === 'not_found')
+                return null;
+            throw error;
+        }
+    });
+}
 export async function diagnoseSquareFile(location) {
     try {
         return { problems: [], ...await inspectFile(await canonicalPath(location), inspectSqlite) };

package/dist/boundary-presentation.d.ts

@@ -1,6 +1,7 @@
-import type { InboxMembership } from './model.js';
-export { pendingAtBoundary } from './square-projections.js';
-export declare function renderPendingAtBoundary(inbox: InboxMembership[]): string;
+import { pendingAtBoundary } from './inbox.js';
+import type { Body, PendingMembership } from './model.js';
+export { pendingAtBoundary };
+export declare function renderPendingAtBoundary(inbox: PendingMembership[]): string;
 /**
  * Serialize a boundary across hook processes so one stale inbox cannot render twice.
  *
@@ -9,4 +10,4 @@ export declare function renderPendingAtBoundary(inbox: InboxMembership[]): strin
  * presentation evidence live, and `presentPending` still re-checks the pending head, join, ownership
  * claim and seen CAS. A source that cannot verify its reuse must read the inbox again.
  */
-export declare function presentPendingAtBoundary<T>(sessionId: string, present: (context: string) => T | Promise<T>, lookup?: (sessionId: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<T | undefined>;
+export declare function presentPendingAtBoundary<T>(identity: Body, present: (context: string) => T | Promise<T>, lookup?: (identity: Body, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<PendingMembership[]> | PendingMembership[], env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<T | undefined>;

package/dist/boundary-presentation.js

@@ -1,15 +1,11 @@
-import { hostLedgerRoot } from './host-ledger-root.js';
+import { squareIndexPath } from './square-index.js';
 import { createHash } from 'node:crypto';
-import path from 'node:path';
 import { withFileLock } from './file-lock.js';
-import { openSquare } from './open-square.js';
-import { closeOpenSquare } from './open-square.js';
+import { createArtifactPort } from './artifact.js';
 import { presentPending } from './presentation-operations.js';
-import { hostLedgerForEnv } from './registry.js';
-import { sessionInbox } from './inbox.js';
+import { sessionInbox, projectBoundaryEligibility, pendingAtBoundary, pendingKey } from './inbox.js';
 import { attentionBodyIsClipped, renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
-import { projectBoundaryEligibility } from './square-projections.js';
-export { pendingAtBoundary } from './square-projections.js';
+export { pendingAtBoundary };
 const CONTEXT_MAX = 1200;
 const presentationLocks = new Map();
 /** One settled promise loses to an abort so an in-process presentation wait stays bounded too. */
@@ -48,9 +44,9 @@ function renderBoundary(inbox) {
         const { membership, notification } = entry;
         const block = [
             renderAttentionPreview({
-                squarePath: membership.squarePath,
+                squarePath: membership.location,
                 actIndex: notification.actIndex,
-                recipient: membership.name,
+                recipient: membership.seat.participant,
                 actor: notification.actor,
                 route: notification.route,
                 body: notification.body,
@@ -74,12 +70,11 @@ function renderBoundary(inbox) {
         complete,
     };
 }
-async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = sessionInbox, env = process.env, signal) {
-    const inbox = await lookup(sessionId, env, signal);
+async function presentPendingAtBoundaryUnlocked(identity, present, lookup = sessionInbox, env = process.env, signal) {
+    const inbox = await lookup(identity, env, signal);
     if (signal?.aborted)
         return undefined;
-    const hostLedger = hostLedgerForEnv(env);
-    const pending = await projectBoundaryEligibility({ hostLedger, sessionId, inbox });
+    const pending = await projectBoundaryEligibility(inbox);
     if (pending.length === 0 || signal?.aborted)
         return undefined;
     const delivered = renderBoundary(pending);
@@ -92,16 +87,17 @@ async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = ses
         result = await present(delivered.context);
     } };
     for (const entry of delivered.complete) {
-        let square;
+        let artifact;
         try {
+            artifact = createArtifactPort(entry.membership.location, undefined, signal);
             try {
-                square = await openSquare(entry.membership.squarePath, { env, signal });
+                await artifact.read(facts => facts.header(), signal);
             }
             catch {
                 continue;
             }
             for (const index of entry.actIndexes) {
-                const key = `${entry.membership.squarePath}\u0000${entry.membership.name.toLocaleLowerCase()}\u0000${index}`;
+                const key = pendingKey(entry.membership, index);
                 const prior = presentationLocks.get(key);
                 if (prior !== undefined) {
                     await awaitWithSignal(prior, signal);
@@ -111,11 +107,11 @@ async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = ses
                         return undefined;
                     continue;
                 }
-                const work = presentPending({ artifact: square.artifact, location: entry.membership.squarePath, participant: entry.membership.name, activity: index, hostLedger: square.hostLedger, session: sessionId, sink: { present: renderOnce }, markSeen: entry.markSeen, now: Date.now(), signal }).then(async (outcome) => {
+                const work = presentPending({ artifact, location: entry.membership.location, participant: entry.membership.seat.participant, activity: index, seat: entry.membership.seat, sink: { present: renderOnce }, markSeen: entry.markSeen, now: Date.now(), signal }).then(async (outcome) => {
                     // A stale projection can outlive its activity; still surface the bounded preview,
                     // but there is no artifact observation to commit.
                     if (!outcome.presented) {
-                        const exists = await square.artifact.read((facts) => facts.activity(index) !== undefined, signal).catch(() => undefined);
+                        const exists = await artifact.read((facts) => facts.activity(index) !== undefined, signal).catch(() => undefined);
                         if (exists?.value === false)
                             await renderOnce();
                     }
@@ -132,8 +128,8 @@ async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = ses
             }
         }
         finally {
-            if (square !== undefined)
-                await closeOpenSquare(square);
+            if (artifact !== undefined)
+                await artifact.close();
         }
     }
     return result;
@@ -146,8 +142,8 @@ async function presentPendingAtBoundaryUnlocked(sessionId, present, lookup = ses
  * presentation evidence live, and `presentPending` still re-checks the pending head, join, ownership
  * claim and seen CAS. A source that cannot verify its reuse must read the inbox again.
  */
-export async function presentPendingAtBoundary(sessionId, present, lookup = sessionInbox, env = process.env, signal) {
-    const ledgerRoot = hostLedgerRoot(env);
-    const ownerKey = createHash('sha256').update(sessionId).digest('hex');
-    return withFileLock(path.join(ledgerRoot, `presentation-boundary-${ownerKey}.lock`), { retryMs: 10, signal }, () => presentPendingAtBoundaryUnlocked(sessionId, present, lookup, env, signal));
+export async function presentPendingAtBoundary(identity, present, lookup = sessionInbox, env = process.env, signal) {
+    const indexPath = squareIndexPath(env);
+    const ownerKey = createHash('sha256').update(JSON.stringify(identity)).digest('hex');
+    return withFileLock(`${indexPath}.boundary-${ownerKey}.lock`, { retryMs: 10, signal }, () => presentPendingAtBoundaryUnlocked(identity, present, lookup, env, signal));
 }

package/dist/catch-decisions.js

@@ -31,7 +31,8 @@ export function catchLimit(value) {
 export function selectCatchPage(facts, requestedName, options) {
     const participant = resolveKnownName(facts, requestedName);
     const limit = catchLimit(options.limit);
-    const filter = { unseenOnly: true, ...(options.from === undefined ? {} : { senders: options.from }), ...(options.mention === true ? { attentionOnly: true } : {}) };
+    const senders = options.from?.map((name) => resolveKnownName(facts, name));
+    const filter = { unseenOnly: true, ...(senders === undefined ? {} : { senders }), ...(options.mention === true ? { attentionOnly: true } : {}) };
     return { participant, indexes: facts.directed(participant, filter, { edge: 'oldest', limit }).items.map((item) => item.index), filter };
 }
 /** Selection, receipts and resulting cursor belong to one artifact write transaction. */

package/dist/claude-delivery-status.d.ts

@@ -1,5 +1,11 @@
-import type { NativeDeliveryObservation } from './host-ledger.js';
-export interface ClaudeDeliveryStatus extends NativeDeliveryObservation {
+export interface ClaudeDeliveryObservation {
+    readonly eventId: string;
+    readonly messageId: string;
+    readonly state: 'held' | 'released' | 'dropped';
+    readonly reason?: string;
+    readonly observedAt: number;
+}
+export interface ClaudeDeliveryStatus extends ClaudeDeliveryObservation {
     readonly provider: 'claude';
     readonly sessionId: string;
 }

package/dist/claude-delivery-status.js

@@ -1,4 +1,5 @@
-import { hostLedgerForEnv } from './registry.js';
+import { createArtifactPort } from './artifact.js';
+import { indexedSquareEntries } from './square-index.js';
 const holdReasons = new Set(['explicit-setting', 'managed-setting', 'repo-setting', 'invalid-setting', 'bypass-default', 'mode-unknown', 'mode-mismatch', 'no-mode-asserted']);
 const dropReasons = new Set(['expired', 'refused', 'dropped', 'discarded']);
 const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -12,13 +13,28 @@ export async function recordClaudeDeliveryStatus(input, env = process.env) {
         || (input.state === 'held' ? !holdReasons.has(input.reason ?? '')
             : input.state === 'dropped' ? !dropReasons.has(input.reason ?? '') : input.reason !== undefined))
         return false;
-    const ledger = hostLedgerForEnv(env);
-    const rows = await ledger.listEvidence({ kind: 'wake', session: input.sessionId, includeReleased: true });
-    const row = rows.find((row) => row.nativeDelivery?.harness === 'claude' && row.nativeDelivery.messageId === input.messageId);
-    if (!row?.claimToken)
-        return false;
-    const { eventId, messageId, state, reason, observedAt } = input;
-    return ledger.observeNativeDelivery({ ...row, claimToken: row.claimToken }, {
-        eventId, messageId, state, ...(reason === undefined ? {} : { reason }), observedAt,
-    });
+    for (const entry of await indexedSquareEntries({ channel: 'claude-code', session: input.sessionId }, env)) {
+        const artifact = createArtifactPort(entry.location);
+        try {
+            const { value: match } = await artifact.read((facts) => facts.roster().flatMap((participant) => {
+                const seat = facts.seat(participant.name);
+                if (seat === undefined || seat.body.session !== input.sessionId || seat.body.channel !== 'claude-code')
+                    return [];
+                const evidence = facts.deliveryEvidence(seat.participant, seat.generation).find((row) => row.correlation?.harness === 'claude' && row.correlation.messageId === input.messageId && row.claimToken !== undefined);
+                return evidence === undefined ? [] : [{ seat, evidence }];
+            }));
+            if (match.length === 0)
+                continue;
+            const { seat, evidence } = match[0];
+            const ref = { participant: seat.participant, body: seat.body, generation: seat.generation };
+            return (await artifact.transactAs({ kind: 'participant', seat: ref }, (facts) => facts.observeNativeDelivery({ seat: ref, claimToken: evidence.claimToken, observation: {
+                    eventId: input.eventId, messageId: input.messageId, state: input.state,
+                    ...(input.reason === undefined ? {} : { reason: input.reason }), observedAt: input.observedAt,
+                } }))).value;
+        }
+        finally {
+            await artifact.close();
+        }
+    }
+    return false;
 }

package/dist/claude-delivery.d.ts

@@ -1,11 +1,15 @@
-import type { HostLedgerPort, PresenceRecord } from './host-ledger.js';
 import type { WakeTransportPort } from './ports.js';
 export declare function nativeTokens(text: string): string[];
 export declare function nativePayload(token: string, preview: string): string;
-export declare function createClaudeWakeTransport(hostLedger: HostLedgerPort, env?: NodeJS.ProcessEnv): WakeTransportPort;
-/** Retired tokens veto a frame; only live correlations and bound memberships confer authority. */
+export declare function createClaudeWakeTransport(env?: NodeJS.ProcessEnv): WakeTransportPort;
+/** Recognize the whole frame first; one inactive token vetoes it before any evidence/receipt write. */
 export declare function observeClaudeDelivery(sessionId: string, text: string, operation: 'guard' | 'admitted' | 'stored', env?: NodeJS.ProcessEnv): Promise<{
     recognized: boolean;
     current: boolean;
 }>;
-export type ClaudeBinding = Pick<PresenceRecord, 'location' | 'participant' | 'session' | 'epoch'>;
+export type ClaudeBinding = {
+    readonly location: string;
+    readonly participant: string;
+    readonly session: string;
+    readonly generation?: import('./square-core.js').ActivityId;
+};