@astrosheep/square 0.3.106 → 0.4.0

package/dist/channel-ports.d.ts

@@ -0,0 +1,241 @@
+import type { Owner } from './neutral.js';
+import type { MessageMetadata, JsonValue, WakeAddress } from './channel-values.js';
+import type { MetadataMatch, DeliveryDeferralFact } from './delivery-deferral.js';
+import type { AttemptOutcome } from './delivery-attempts.js';
+import type { MessageId } from './message.js';
+import type { EndpointGeneration } from './message.js';
+export type { MessageId, EndpointGeneration };
+/** One lower write's custody claim. Every Channel mutation carries exactly one. */
+export type ChannelWriteAuthority = {
+    readonly kind: 'send';
+    readonly actor: string;
+} | {
+    readonly kind: 'endpoint';
+    readonly participant: string;
+    readonly owner: Owner;
+} | {
+    readonly kind: 'endpoint-cleanup';
+    readonly seat: EndpointRef;
+} | {
+    readonly kind: 'participant';
+    readonly seat: EndpointRef;
+};
+/** The only storage surface a Channel is allowed to see: messages, endpoints and their custody. */
+export interface ChannelArtifact {
+    read<T>(select: (facts: ChannelRead) => T, signal?: AbortSignal): Promise<{
+        readonly value: T;
+        readonly version: number;
+    }>;
+    transactAs<T>(authority: ChannelWriteAuthority, change: (facts: ChannelWrite) => T, signal?: AbortSignal): Promise<{
+        readonly value: T;
+        readonly changed: boolean;
+    }>;
+    claimDelivery(input: ChannelDeliveryClaimInput, signal?: AbortSignal): Promise<ChannelDeliveryClaimResult>;
+    prepareDelivery(input: ChannelDeliveryPreparation, signal?: AbortSignal): Promise<boolean>;
+    completeDelivery(input: ChannelDeliveryCompletion, signal?: AbortSignal): Promise<boolean>;
+    cancelDeliveries(seat: EndpointRef, through?: number, signal?: AbortSignal): Promise<boolean>;
+    changed(sinceVersion: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    close(): Promise<void>;
+}
+export interface ChannelHeader {
+    readonly revision: number;
+    readonly deliveryRevision: number;
+    readonly nextMessageIndex: number;
+    readonly lastMessageIndex: number;
+}
+/** One Channel message. Body and caller metadata have exactly one authoritative copy. */
+export interface MessageFact {
+    readonly index: number;
+    readonly at: number;
+    readonly from: string;
+    readonly body: string;
+    readonly metadata?: MessageMetadata;
+    /** Sender-chosen preview projection; the stored body remains full. */
+    readonly preview?: string;
+}
+export interface MessageAddressFact {
+    readonly recipient: string;
+    readonly generation?: EndpointGeneration;
+}
+export interface MessageHead {
+    readonly index: number;
+    readonly at: number;
+    readonly from: string;
+    readonly recipient: string;
+    readonly generation?: EndpointGeneration;
+}
+export interface MessageFilter {
+    readonly afterIndex?: number;
+    readonly beforeIndex?: number;
+    readonly throughIndex?: number;
+    readonly indexes?: readonly number[];
+    readonly senders?: readonly string[];
+    readonly senderMatch?: 'identity' | 'exact';
+    readonly afterAt?: number;
+    readonly metadataMatch?: MetadataMatch;
+    readonly search?: {
+        readonly text: string;
+        readonly mode: 'literal' | 'regex';
+    };
+    readonly unseenOnly?: true;
+    readonly currentGeneration?: true;
+}
+export interface MessageDraft {
+    readonly from: string;
+    readonly at: number;
+    readonly body: string;
+    readonly metadata?: MessageMetadata;
+    readonly preview?: string;
+    readonly to: readonly MessageAddressFact[];
+}
+export interface EndpointFact {
+    readonly participant: string;
+    readonly owner: Owner;
+    readonly generation: EndpointGeneration;
+    readonly attachment: 'attached' | 'detached';
+    readonly wakeAddress?: WakeAddress;
+}
+export type EndpointRef = Pick<EndpointFact, 'participant' | 'owner' | 'generation'>;
+/** Upper-owned namespace association; Channel never interprets its selector. */
+export interface ReceiveClaimFact {
+    readonly namespace: string;
+    readonly id: string;
+    readonly owner: string;
+    readonly generation: EndpointGeneration;
+    readonly selector: JsonValue;
+    /** Message-scoped suppression coverage; Channel owns this list, the selector stays opaque. */
+    readonly suppressed: readonly number[];
+    readonly heartbeatAt: number;
+    readonly expiresAt: number;
+}
+export interface ChannelDeliveryEvidence {
+    readonly participant: string;
+    readonly generation: EndpointGeneration;
+    readonly message: MessageId;
+    readonly kind: 'wake' | 'presentation';
+    readonly outcome: AttemptOutcome;
+    readonly attemptN: number;
+    readonly at: number;
+    readonly expiresAt?: number;
+    readonly claimToken?: string;
+    readonly route?: WakeAddress;
+    readonly signature?: string;
+    readonly messageText?: string;
+    readonly diagnostic?: JsonValue;
+    readonly correlation?: {
+        readonly harness: 'claude' | 'opencode' | 'pi';
+        readonly token?: string;
+        readonly messageId?: string;
+        readonly payloadHash?: string;
+    };
+    /** Exact bytes prepared for this attempt; declared before the external effect. */
+    readonly coverage?: 'full' | 'clipped';
+    readonly description?: string;
+    readonly nativeObservations?: readonly {
+        readonly eventId: string;
+        readonly messageId: string;
+        readonly state: 'held' | 'released' | 'dropped';
+        readonly reason?: string;
+        readonly observedAt: number;
+    }[];
+}
+export interface ChannelDeliveryClaimInput {
+    readonly seat: EndpointRef;
+    readonly message: MessageId;
+    readonly kind: 'wake' | 'presentation';
+    readonly observationOf?: string;
+    readonly route?: WakeAddress;
+    readonly at: number;
+    readonly leaseMs: number;
+    readonly claimToken: string;
+}
+export type ChannelDeliveryClaimResult = {
+    readonly status: 'acquired';
+    readonly claimToken: string;
+    readonly attemptN: number;
+} | {
+    readonly status: 'busy' | 'terminal' | 'stale' | 'deferred';
+    readonly evidence?: ChannelDeliveryEvidence;
+};
+export interface ChannelDeliveryPreparation {
+    readonly seat: EndpointRef;
+    readonly claimToken: string;
+    readonly correlation: NonNullable<ChannelDeliveryEvidence['correlation']>;
+    readonly coverage: 'full' | 'clipped';
+    readonly description?: string;
+}
+export interface ChannelDeliveryCompletion {
+    readonly seat: EndpointRef;
+    readonly message: MessageId;
+    readonly claimToken: string;
+    readonly outcome: Exclude<ChannelDeliveryEvidence['outcome'], 'dispatching'>;
+    readonly at: number;
+    readonly signature?: string;
+    readonly messageText?: string;
+    readonly diagnostic?: JsonValue;
+    readonly correlation?: ChannelDeliveryEvidence['correlation'];
+}
+/** Lower read capabilities. Nothing here describes Agora events, routes or attention. */
+export interface ChannelRead {
+    header(): ChannelHeader;
+    message(index: number): MessageFact | undefined;
+    messages(indexes: readonly number[]): readonly MessageFact[];
+    messageHeads(filter: MessageFilter, page: {
+        readonly edge: 'oldest' | 'newest';
+        readonly limit: number;
+    }): {
+        readonly items: readonly MessageFact[];
+        readonly hasMore: boolean;
+    };
+    messageCount(filter: MessageFilter): number;
+    addresses(index: number): readonly MessageAddressFact[];
+    receipt(owner: string, index: number): {
+        readonly at: number;
+    } | undefined;
+    receiptFacts(owner: string, afterIndex: number): {
+        readonly latestAt?: number;
+        readonly latestActorMessageIndex?: number;
+    };
+    directed(recipient: string, filter: MessageFilter, page: {
+        readonly edge: 'oldest' | 'newest';
+        readonly limit: number;
+    }): {
+        readonly items: readonly MessageHead[];
+        readonly hasMore: boolean;
+    };
+    directedCount(recipient: string, filter: MessageFilter): number;
+    endpoint(requested: string): EndpointFact | undefined;
+    endpointsForOwner(owner: Owner): readonly EndpointFact[];
+    endpoints(): readonly EndpointFact[];
+    deliveryEvidence(participant: string, generation: EndpointGeneration, message?: MessageId): readonly ChannelDeliveryEvidence[];
+    deliveryByToken(claimToken: string): ChannelDeliveryEvidence | undefined;
+    cancelledThrough(participant: string, generation: EndpointGeneration): number | undefined;
+    deliveryDeferrals(participant: string, generation: EndpointGeneration): readonly DeliveryDeferralFact[];
+    receiveClaims(owner: string, namespace?: string): readonly ReceiveClaimFact[];
+    claimLease(owner: string, namespace?: string): ReceiveClaimFact | undefined;
+    /** Any live claim of this endpoint covering the message suppresses its pending eligibility. */
+    suppressed(owner: string, generation: EndpointGeneration, index: number, now: number): boolean;
+}
+export interface ChannelWrite extends ChannelRead {
+    publishMessage(draft: MessageDraft): MessageFact;
+    storeEndpoint(endpoint: EndpointFact): boolean;
+    updateWakeAddress(endpoint: EndpointRef, wakeAddress?: WakeAddress): boolean;
+    reattachEndpoint(endpoint: EndpointRef, wakeAddress?: WakeAddress): boolean;
+    detachEndpoint(endpoint: EndpointRef): boolean;
+    removeEndpoint(endpoint: EndpointRef): boolean;
+    cancelThrough(endpoint: EndpointRef, through: number): boolean;
+    markSeen(owner: string, indexes: readonly number[], at: number): number;
+    claimDelivery(input: ChannelDeliveryClaimInput): ChannelDeliveryClaimResult;
+    prepareDelivery(input: ChannelDeliveryPreparation): boolean;
+    completeDelivery(input: ChannelDeliveryCompletion): boolean;
+    observeNativeDelivery(input: {
+        readonly seat: EndpointRef;
+        readonly claimToken: string;
+        readonly observation: NonNullable<ChannelDeliveryEvidence['nativeObservations']>[number];
+    }): boolean;
+    putDeliveryDeferral(seat: EndpointRef, id: string, match: MetadataMatch, expiresAt: number, now: number): boolean;
+    renewDeliveryDeferral(seat: EndpointRef, id: string, expiresAt: number, now: number): boolean;
+    releaseDeliveryDeferral(seat: EndpointRef, id: string, now: number): boolean;
+    putReceiveClaim(claim: ReceiveClaimFact): boolean;
+    removeReceiveClaim(owner: string, namespace: string, id: string): boolean;
+}

package/dist/channel-ports.js

@@ -0,0 +1 @@
+export {};

package/dist/channel-presentation.d.ts

@@ -0,0 +1,17 @@
+export declare function escapeSquareTags(text: string): string;
+/** A Channel message has no Agora route or activity record. */
+export declare function projectChannelNotification({ actor, body, preview }: {
+    squarePath: string;
+    recipient: string;
+    actor: string;
+    body: string;
+    preview?: string;
+}): {
+    text: string;
+    full: string;
+    preview: string;
+    description: string;
+    clipped: boolean;
+};
+/** The fixed model-facing outer frame, independent of transport and source. */
+export declare function renderSquareReminder(previews: readonly string[]): string;

package/dist/channel-presentation.js

@@ -0,0 +1,22 @@
+export function escapeSquareTags(text) {
+    return text.replace(/<(\/?)(square-|channel-|system-reminder)/gi, '<\\$1$2');
+}
+/** A Channel message has no Agora route or activity record. */
+export function projectChannelNotification({ actor, body, preview }) {
+    const compact = body.replace(/\r\n/g, '\n');
+    const projected = preview ?? compact;
+    return {
+        // Channel's default notification is the full (or explicitly previewed) escaped body.
+        text: escapeSquareTags(projected),
+        // Human expansion is the stored full body, never a sender-owned preview.
+        full: compact,
+        preview: projected, description: `${actor} sent you a message`, clipped: projected !== compact,
+    };
+}
+/** The fixed model-facing outer frame, independent of transport and source. */
+export function renderSquareReminder(previews) {
+    if (previews.length === 0)
+        return '';
+    return ['', '<system-reminder>', 'This is an external notification, not a direct message from the user.', '',
+        previews.join('\n\n'), '</system-reminder>', ''].join('\n');
+}

package/dist/channel-sqlite-schema.d.ts

@@ -0,0 +1,13 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { StoreFormat } from './artifact-store.js';
+/** Channel owns this schema in both standalone and composed artifacts. */
+export declare const CHANNEL_SCHEMA_SQL = "CREATE TABLE channel_meta (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  next_msg_index INTEGER NOT NULL CHECK (next_msg_index BETWEEN 0 AND 9007199254740991),\n  description TEXT NOT NULL\n);\nCREATE TABLE messages (\n  msg_index INTEGER PRIMARY KEY CHECK (msg_index BETWEEN 0 AND 9007199254740991),\n  at REAL NOT NULL, from_json TEXT NOT NULL, from_key_json TEXT NOT NULL,\n  body_json TEXT NOT NULL CHECK (json_valid(body_json)),\n  metadata_json TEXT CHECK (metadata_json IS NULL OR json_valid(metadata_json)), preview TEXT\n);\nCREATE INDEX message_sender ON messages(from_key_json,msg_index);\nCREATE TABLE message_addresses (\n  msg_index INTEGER NOT NULL, recipient_key_json TEXT NOT NULL, recipient_json TEXT NOT NULL,\n  recipient_order INTEGER NOT NULL CHECK (recipient_order >= 0), generation_json TEXT,\n  PRIMARY KEY (msg_index,recipient_key_json), UNIQUE(msg_index,recipient_order)\n) WITHOUT ROWID;\nCREATE INDEX message_recipient ON message_addresses(recipient_key_json,msg_index);\nCREATE TABLE receipts (\n  owner_key_json TEXT NOT NULL, msg_index INTEGER NOT NULL, at REAL NOT NULL,\n  PRIMARY KEY (owner_key_json,msg_index)\n) WITHOUT ROWID;\nCREATE INDEX receipt_owner_time ON receipts(owner_key_json,at);\nCREATE TABLE endpoints (\n  participant_key_json TEXT PRIMARY KEY NOT NULL, participant_json TEXT NOT NULL,\n  owner_json TEXT NOT NULL, generation_json TEXT NOT NULL,\n  wake_address_json TEXT CHECK (wake_address_json IS NULL OR json_valid(wake_address_json)),\n  attachment TEXT NOT NULL CHECK (attachment IN ('attached','detached'))\n) WITHOUT ROWID;\nCREATE INDEX endpoint_owner ON endpoints(owner_json);\nCREATE TABLE delivery_evidence (\n  participant_key_json TEXT NOT NULL, participant_json TEXT NOT NULL, generation_json TEXT NOT NULL,\n  msg_index INTEGER NOT NULL, kind TEXT NOT NULL CHECK (kind IN ('wake','presentation')),\n  attempt_n INTEGER NOT NULL CHECK (attempt_n >= 0), outcome TEXT NOT NULL,\n  at REAL NOT NULL, expires_at REAL, claim_token_json TEXT,\n  payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),\n  PRIMARY KEY (participant_key_json,generation_json,msg_index,kind,attempt_n)\n) WITHOUT ROWID;\nCREATE UNIQUE INDEX delivery_claim_token ON delivery_evidence(claim_token_json) WHERE claim_token_json IS NOT NULL;\nCREATE TABLE delivery_cancellations (\n  participant_key_json TEXT NOT NULL, generation_json TEXT NOT NULL, through_index INTEGER NOT NULL,\n  PRIMARY KEY (participant_key_json,generation_json)\n) WITHOUT ROWID;\nCREATE TABLE delivery_deferrals (\n  participant_key_json TEXT NOT NULL, participant_json TEXT NOT NULL, generation_json TEXT NOT NULL,\n  deferral_id_json TEXT NOT NULL, match_json TEXT NOT NULL CHECK (json_valid(match_json)), expires_at REAL NOT NULL,\n  PRIMARY KEY (participant_key_json,generation_json,deferral_id_json)\n) WITHOUT ROWID;\nCREATE INDEX delivery_deferral_expiry ON delivery_deferrals(participant_key_json,generation_json,expires_at);\nCREATE TABLE receive_claims (\n  namespace_key_json TEXT NOT NULL, owner_key_json TEXT NOT NULL, generation_json TEXT NOT NULL,\n  claim_id_json TEXT NOT NULL, heartbeat_at REAL NOT NULL, expires_at REAL NOT NULL CHECK (expires_at >= heartbeat_at),\n  selector_json TEXT NOT NULL CHECK (json_valid(selector_json)), suppressed_json TEXT NOT NULL CHECK (json_valid(suppressed_json)),\n  PRIMARY KEY (namespace_key_json,owner_key_json)\n) WITHOUT ROWID;";
+export declare function initializeChannelSqlite(db: DatabaseSync, description?: string): void;
+export declare function resetChannelSqlite(db: DatabaseSync): void;
+export declare const channelLowerSchema: {
+    schemaSql: string;
+    initialize: typeof initializeChannelSqlite;
+    reset: typeof resetChannelSqlite;
+};
+export declare const channelStoreFormat: StoreFormat;
+export declare function initializeStandaloneChannel(db: DatabaseSync, revision?: number, description?: string): void;

package/dist/channel-sqlite-schema.js

@@ -0,0 +1,81 @@
+import { initializeStorageMeta, resetStorageMeta, STORAGE_META_SQL, validateSchema } from './sqlite-framing.js';
+import { requireFact } from './sqlite-values.js';
+/** Channel owns this schema in both standalone and composed artifacts. */
+export const CHANNEL_SCHEMA_SQL = `CREATE TABLE channel_meta (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  next_msg_index INTEGER NOT NULL CHECK (next_msg_index BETWEEN 0 AND 9007199254740991),
+  description TEXT NOT NULL
+);
+CREATE TABLE messages (
+  msg_index INTEGER PRIMARY KEY CHECK (msg_index BETWEEN 0 AND 9007199254740991),
+  at REAL NOT NULL, from_json TEXT NOT NULL, from_key_json TEXT NOT NULL,
+  body_json TEXT NOT NULL CHECK (json_valid(body_json)),
+  metadata_json TEXT CHECK (metadata_json IS NULL OR json_valid(metadata_json)), preview TEXT
+);
+CREATE INDEX message_sender ON messages(from_key_json,msg_index);
+CREATE TABLE message_addresses (
+  msg_index INTEGER NOT NULL, recipient_key_json TEXT NOT NULL, recipient_json TEXT NOT NULL,
+  recipient_order INTEGER NOT NULL CHECK (recipient_order >= 0), generation_json TEXT,
+  PRIMARY KEY (msg_index,recipient_key_json), UNIQUE(msg_index,recipient_order)
+) WITHOUT ROWID;
+CREATE INDEX message_recipient ON message_addresses(recipient_key_json,msg_index);
+CREATE TABLE receipts (
+  owner_key_json TEXT NOT NULL, msg_index INTEGER NOT NULL, at REAL NOT NULL,
+  PRIMARY KEY (owner_key_json,msg_index)
+) WITHOUT ROWID;
+CREATE INDEX receipt_owner_time ON receipts(owner_key_json,at);
+CREATE TABLE endpoints (
+  participant_key_json TEXT PRIMARY KEY NOT NULL, participant_json TEXT NOT NULL,
+  owner_json TEXT NOT NULL, generation_json TEXT NOT NULL,
+  wake_address_json TEXT CHECK (wake_address_json IS NULL OR json_valid(wake_address_json)),
+  attachment TEXT NOT NULL CHECK (attachment IN ('attached','detached'))
+) WITHOUT ROWID;
+CREATE INDEX endpoint_owner ON endpoints(owner_json);
+CREATE TABLE delivery_evidence (
+  participant_key_json TEXT NOT NULL, participant_json TEXT NOT NULL, generation_json TEXT NOT NULL,
+  msg_index INTEGER NOT NULL, kind TEXT NOT NULL CHECK (kind IN ('wake','presentation')),
+  attempt_n INTEGER NOT NULL CHECK (attempt_n >= 0), outcome TEXT NOT NULL,
+  at REAL NOT NULL, expires_at REAL, claim_token_json TEXT,
+  payload_json TEXT NOT NULL CHECK (json_valid(payload_json)),
+  PRIMARY KEY (participant_key_json,generation_json,msg_index,kind,attempt_n)
+) WITHOUT ROWID;
+CREATE UNIQUE INDEX delivery_claim_token ON delivery_evidence(claim_token_json) WHERE claim_token_json IS NOT NULL;
+CREATE TABLE delivery_cancellations (
+  participant_key_json TEXT NOT NULL, generation_json TEXT NOT NULL, through_index INTEGER NOT NULL,
+  PRIMARY KEY (participant_key_json,generation_json)
+) WITHOUT ROWID;
+CREATE TABLE delivery_deferrals (
+  participant_key_json TEXT NOT NULL, participant_json TEXT NOT NULL, generation_json TEXT NOT NULL,
+  deferral_id_json TEXT NOT NULL, match_json TEXT NOT NULL CHECK (json_valid(match_json)), expires_at REAL NOT NULL,
+  PRIMARY KEY (participant_key_json,generation_json,deferral_id_json)
+) WITHOUT ROWID;
+CREATE INDEX delivery_deferral_expiry ON delivery_deferrals(participant_key_json,generation_json,expires_at);
+CREATE TABLE receive_claims (
+  namespace_key_json TEXT NOT NULL, owner_key_json TEXT NOT NULL, generation_json TEXT NOT NULL,
+  claim_id_json TEXT NOT NULL, heartbeat_at REAL NOT NULL, expires_at REAL NOT NULL CHECK (expires_at >= heartbeat_at),
+  selector_json TEXT NOT NULL CHECK (json_valid(selector_json)), suppressed_json TEXT NOT NULL CHECK (json_valid(suppressed_json)),
+  PRIMARY KEY (namespace_key_json,owner_key_json)
+) WITHOUT ROWID;`;
+export function initializeChannelSqlite(db, description = '# Channel\n') {
+    db.exec(CHANNEL_SCHEMA_SQL);
+    db.prepare('INSERT INTO channel_meta(id,next_msg_index,description) VALUES(1,0,?)').run(description);
+}
+export function resetChannelSqlite(db) {
+    for (const table of ['receive_claims', 'delivery_deferrals', 'delivery_cancellations', 'delivery_evidence', 'endpoints', 'receipts', 'message_addresses', 'messages', 'channel_meta'])
+        db.exec(`DROP TABLE ${table}`);
+}
+export const channelLowerSchema = { schemaSql: CHANNEL_SCHEMA_SQL, initialize: initializeChannelSqlite, reset: resetChannelSqlite };
+export const channelStoreFormat = {
+    applicationId: 0x43484e4c, userVersion: 1, observerKey: 'channel',
+    validate(db, location) {
+        const identity = db.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
+        requireFact(identity.application_id === this.applicationId, 'unrelated SQLite database.');
+        requireFact(identity.user_version === this.userVersion, 'unsupported Channel SQLite format version.');
+        validateSchema(db, `${STORAGE_META_SQL}\n${CHANNEL_SCHEMA_SQL}`, location);
+    },
+    reset(db) { resetChannelSqlite(db); resetStorageMeta(db); },
+};
+export function initializeStandaloneChannel(db, revision = 0, description = '# Channel\n') {
+    initializeStorageMeta(db, revision);
+    initializeChannelSqlite(db, description);
+}

package/dist/channel-transport.d.ts

@@ -0,0 +1,62 @@
+import type { WakeRoute } from './channel-values.js';
+import type { MessageId } from './message.js';
+/** One wake executor; final send must use the supplied custody gate. */
+export interface WakeTransportPort {
+    probe?(route: WakeRoute): Promise<boolean | {
+        readonly outcome: 'not-capable';
+        readonly diagnostic?: string;
+    }>;
+    attempt(request: WakeRequest, timeoutMs: number, beforeSend: () => Promise<boolean>): Promise<WakeOutcome>;
+}
+export interface WakePresentation {
+    readonly payload: string;
+    readonly coverage: 'full' | 'clipped';
+    readonly description?: string;
+}
+export interface WakeProjectionContext {
+    readonly location: string;
+    readonly participant: string;
+    readonly message: MessageId;
+    readonly actor: string;
+    readonly seat: {
+        readonly participant: string;
+        readonly owner: string;
+        readonly generation: string;
+    };
+    readonly route: WakeRoute;
+}
+export type WakeProjection = (context: WakeProjectionContext) => Promise<WakePresentation | undefined>;
+export interface WakeRequest extends WakeProjectionContext {
+    readonly claimToken?: string;
+    readonly attemptN?: number;
+    readonly channel: {
+        prepare(input: {
+            readonly correlation: {
+                readonly harness: 'claude' | 'opencode' | 'pi';
+                readonly token?: string;
+                readonly messageId?: string;
+                readonly payloadHash?: string;
+            };
+            readonly coverage: 'full' | 'clipped';
+            readonly description?: string;
+        }, signal?: AbortSignal): Promise<boolean>;
+    };
+    readonly presentation?: WakePresentation;
+}
+export type WakeOutcome = {
+    readonly outcome: 'accepted';
+    readonly signature?: string;
+} | {
+    readonly outcome: 'failed';
+    readonly message?: string;
+    readonly signature?: string;
+    readonly diagnostic?: unknown;
+} | {
+    readonly outcome: 'not-capable';
+    readonly diagnostic?: string;
+} | {
+    readonly outcome: 'unknown';
+    readonly signature?: string;
+    readonly message?: string;
+    readonly diagnostic?: unknown;
+};

package/dist/channel-transport.js

@@ -0,0 +1 @@
+export {};

package/dist/channel-values.d.ts

@@ -0,0 +1,27 @@
+export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-queue", "claude-native", "paseo", "http"];
+export type WakeRouteKind = typeof WAKE_ROUTE_KINDS[number];
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type MessageMetadata = Readonly<Record<string, JsonValue>>;
+export declare const MESSAGE_METADATA_MAX_BYTES: number;
+export declare const MESSAGE_METADATA_MAX_DEPTH = 256;
+/** Validate the bounded, lossless JSON object carried by a message. */
+export declare function validateMessageMetadata(value: unknown): MessageMetadata | undefined;
+export declare function messageMetadataHasContent(metadata: MessageMetadata | undefined): boolean;
+export interface WakeAddress {
+    readonly kind: WakeRouteKind;
+    readonly address: Readonly<Record<string, string>>;
+}
+export declare function isWakeRouteKind(value: unknown): value is WakeRouteKind;
+export interface WakeRoute {
+    epoch?: number;
+    location: string;
+    participant: string;
+    kind: WakeRouteKind;
+    address: Record<string, string>;
+    updatedAt: number;
+}
+export declare function sameName(a: string, b: string): boolean;
+export declare const NAME_GRAPHEME_SOURCE: string;
+export declare function validateName(name: string): void;

package/dist/channel-values.js

@@ -0,0 +1,90 @@
+import { SquareError, nameKey } from './neutral.js';
+export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-queue', 'claude-native', 'paseo', 'http'];
+export const MESSAGE_METADATA_MAX_BYTES = 16 * 1024;
+export const MESSAGE_METADATA_MAX_DEPTH = 256;
+/** Validate the bounded, lossless JSON object carried by a message. */
+export function validateMessageMetadata(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new SquareError('invalid_args', 'Activity metadata must be a non-null JSON object.');
+    const visiting = new Set();
+    const stack = [{ value, depth: 0 }];
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        if (frame.exit !== undefined) {
+            visiting.delete(frame.exit);
+            continue;
+        }
+        const item = frame.value;
+        if (item === null || typeof item === 'boolean' || typeof item === 'string')
+            continue;
+        if (typeof item === 'number') {
+            if (!Number.isFinite(item))
+                throw new SquareError('invalid_args', 'Activity metadata must contain only finite JSON values.');
+            continue;
+        }
+        if (typeof item !== 'object')
+            throw new SquareError('invalid_args', 'Activity metadata must contain only JSON values.');
+        if (frame.depth > MESSAGE_METADATA_MAX_DEPTH)
+            throw new SquareError('invalid_args', `Activity metadata nesting cannot exceed ${MESSAGE_METADATA_MAX_DEPTH} levels.`);
+        if (visiting.has(item))
+            throw new SquareError('invalid_args', 'Activity metadata cannot contain a cycle.');
+        visiting.add(item);
+        stack.push({ value: item, depth: frame.depth, exit: item });
+        if (Array.isArray(item)) {
+            if (Object.getOwnPropertySymbols(item).length > 0 || Object.keys(item).length !== item.length)
+                throw new SquareError('invalid_args', 'Activity metadata arrays must be dense JSON arrays.');
+            const names = Object.getOwnPropertyNames(item);
+            if (names.some(name => name !== 'length' && (!/^(0|[1-9]\d*)$/.test(name) || Number(name) >= item.length)))
+                throw new SquareError('invalid_args', 'Activity metadata arrays must contain only indexed values.');
+            for (const key of Object.keys(item).reverse()) {
+                const descriptor = Object.getOwnPropertyDescriptor(item, key);
+                if (descriptor === undefined || !('value' in descriptor))
+                    throw new SquareError('invalid_args', 'Activity metadata cannot contain accessors.');
+                stack.push({ value: descriptor.value, depth: frame.depth + 1 });
+            }
+            continue;
+        }
+        const prototype = Object.getPrototypeOf(item);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new SquareError('invalid_args', 'Activity metadata must contain only plain JSON objects.');
+        if (Object.getOwnPropertySymbols(item).length > 0)
+            throw new SquareError('invalid_args', 'Activity metadata cannot contain symbol keys.');
+        const names = Object.getOwnPropertyNames(item);
+        if (names.some(name => !Object.prototype.propertyIsEnumerable.call(item, name)))
+            throw new SquareError('invalid_args', 'Activity metadata cannot contain non-enumerable properties.');
+        for (const name of names.reverse()) {
+            const descriptor = Object.getOwnPropertyDescriptor(item, name);
+            if (!('value' in descriptor))
+                throw new SquareError('invalid_args', 'Activity metadata cannot contain accessors.');
+            stack.push({ value: descriptor.value, depth: frame.depth + 1 });
+        }
+    }
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch {
+        throw new SquareError('invalid_args', 'Activity metadata must contain only lossless JSON values.');
+    }
+    if (serialized === undefined || Buffer.byteLength(serialized, 'utf8') > MESSAGE_METADATA_MAX_BYTES)
+        throw new SquareError('invalid_args', `Activity metadata cannot exceed ${MESSAGE_METADATA_MAX_BYTES} UTF-8 bytes.`);
+    return value;
+}
+export function messageMetadataHasContent(metadata) {
+    return metadata !== undefined && Object.keys(metadata).length > 0;
+}
+export function isWakeRouteKind(value) {
+    return typeof value === 'string' && WAKE_ROUTE_KINDS.includes(value);
+}
+export function sameName(a, b) { return nameKey(a) === nameKey(b); }
+const TEXT_NAME_GRAPHEME_SOURCE = String.raw `[[\p{L}\p{N}\p{M}_\x2D]--[\p{Variation_Selector}]]`;
+export const NAME_GRAPHEME_SOURCE = String.raw `${TEXT_NAME_GRAPHEME_SOURCE}|\p{RGI_Emoji}`;
+const TEXT_NAME_PATTERN = new RegExp(`^(?:${TEXT_NAME_GRAPHEME_SOURCE})+(?:/(?:${TEXT_NAME_GRAPHEME_SOURCE})+)*$`, 'v');
+const NAME_PATTERN = new RegExp(`^(?:${NAME_GRAPHEME_SOURCE})+(?:/(?:${NAME_GRAPHEME_SOURCE})+)*$`, 'v');
+export function validateName(name) {
+    if (!name || (!TEXT_NAME_PATTERN.test(name) && !NAME_PATTERN.test(name))) {
+        throw new SquareError('invalid_name', 'Invalid name: names must contain non-empty slash-separated segments using Unicode letters, digits, marks, hyphens, underscores, or complete RGI emoji graphemes.');
+    }
+}