@astrosheep/square 0.4.0 → 0.4.2

package/dist/channel-artifact.js

@@ -1,55 +0,0 @@
-import { createArtifactStore, createStoreFile, replaceStoreFile } from './artifact-store.js';
-import { channelStoreFormat, initializeStandaloneChannel } from './channel-sqlite-schema.js';
-import { createChannelSqlite } from './sqlite-channel.js';
-import { wrapChannelWrite } from './channel-domain.js';
-import { deliverPending } from './delivery-operations.js';
-import { InternalSquareError } from './neutral.js';
-const readMethods = [
-    'header', 'message', 'messages', 'messageHeads', 'messageCount', 'addresses', 'receipt', 'receiptFacts',
-    'directed', 'directedCount', 'endpoint', 'endpointsForOwner', 'endpoints', 'deliveryEvidence', 'deliveryByToken',
-    'cancelledThrough', 'deliveryDeferrals', 'receiveClaims', 'claimLease', 'suppressed',
-];
-export function channelReads(channel, guard) {
-    return Object.fromEntries(readMethods.map(name => [name, guard(channel[name])]));
-}
-export function channelWrites(channel, guard) {
-    return Object.fromEntries(Object.entries(channel).filter(([, value]) => typeof value === 'function')
-        .map(([name, value]) => [name, guard(value)]));
-}
-function channelPort(location, initialize, signal) {
-    const store = createArtifactStore(location, channelStoreFormat, initialize, signal);
-    const port = {
-        read: (select, signal) => store.run(false, ({ db, guard }) => select(channelReads(createChannelSqlite(db), guard)), signal),
-        transactAs: (authority, change, signal) => store.run(true, ({ db, guard, track }) => {
-            const channel = createChannelSqlite(db);
-            track(channel);
-            return change(wrapChannelWrite(channelReads(channel, guard), channelWrites(channel, guard), authority));
-        }, signal),
-        async claimDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.claimDelivery(input), signal)).value; },
-        async prepareDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.prepareDelivery(input), signal)).value; },
-        async completeDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.completeDelivery(input), signal)).value; },
-        async cancelDeliveries(seat, through, signal) {
-            return (await port.transactAs({ kind: 'participant', seat }, facts => {
-                const boundary = through ?? facts.header().lastMessageIndex;
-                return boundary < 0 ? false : facts.cancelThrough(seat, boundary);
-            }, signal)).value;
-        },
-        changed: store.changed, close: store.close,
-    };
-    return port;
-}
-/** Native Channel factories use only lower SQL and the shared physical-store lifetime. */
-export function openChannelArtifact(location, signal) { return channelPort(location, undefined, signal); }
-export function createMemoryChannelArtifact(description = '# Channel\n') {
-    return channelPort(':memory:', db => initializeStandaloneChannel(db, 0, description));
-}
-export async function createChannelArtifactFile(location, description, force, signal) {
-    if (force)
-        await replaceStoreFile(location, channelStoreFormat, (db, revision) => initializeStandaloneChannel(db, revision, description), signal);
-    else if (!await createStoreFile(location, channelStoreFormat, db => initializeStandaloneChannel(db, 0, description), signal))
-        throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${location}\nPass -f to overwrite.`);
-}
-export function channelCourier(artifact, transport, location, clock, preparePresentation) {
-    return (message) => deliverPending({ artifact, transport, location, now: clock(),
-        ...(preparePresentation === undefined ? {} : { preparePresentation }), ...(message === undefined ? {} : { message }) });
-}

package/dist/channel-delivery.d.ts

@@ -1,11 +0,0 @@
-import type { ChannelRead, ChannelDeliveryEvidence as DeliveryEvidence, MessageHead } from './channel-ports.js';
-/** Presentation custody blocks a wake, independently of native wake acceptance. */
-export declare function presentationBlocksWake(evidence: readonly DeliveryEvidence[], now: number): boolean;
-/** Preselection only: an expired wake dispatch is uncertain, never safe automatic replay. */
-export declare function automaticWakeEligible(evidence: readonly DeliveryEvidence[], now: number): boolean;
-/** One lower pending message: attached, unconsumed and not suppressed by a live claim. */
-export declare function pendingHeadAt(facts: ChannelRead, name: string, index: number, now?: number): MessageHead | undefined;
-/** Lower pending selection for one recipient, oldest first. */
-export declare function pendingMessageHeads(facts: ChannelRead, name: string, now?: number, suppress?: boolean): MessageHead[];
-/** Lower recipients of one message that still owe a wake; other endpoints are untouched. */
-export declare function pendingAddresses(facts: ChannelRead, index: number, now?: number): readonly MessageHead[];

package/dist/channel-delivery.js

@@ -1,51 +0,0 @@
-import { automaticDispatchEligible, presentationBlocksDispatch } from './delivery-attempts.js';
-function custody(evidence) {
-    return evidence.map(row => ({ purpose: row.kind === 'wake' ? 'dispatch' : 'presentation', outcome: row.outcome, expiresAt: row.expiresAt }));
-}
-/** Presentation custody blocks a wake, independently of native wake acceptance. */
-export function presentationBlocksWake(evidence, now) {
-    return presentationBlocksDispatch(custody(evidence), now);
-}
-/** Preselection only: an expired wake dispatch is uncertain, never safe automatic replay. */
-export function automaticWakeEligible(evidence, now) {
-    return automaticDispatchEligible(custody(evidence), now);
-}
-/** One lower pending message: attached, unconsumed and not suppressed by a live claim. */
-export function pendingHeadAt(facts, name, index, now = Date.now()) {
-    const endpoint = facts.endpoint(name);
-    if (endpoint === undefined || endpoint.attachment !== 'attached' || facts.receipt(endpoint.participant, index))
-        return undefined;
-    if (facts.suppressed(endpoint.participant, endpoint.generation, index, now))
-        return undefined;
-    return facts.directed(endpoint.participant, { afterIndex: index - 1, throughIndex: index, currentGeneration: true }, { edge: 'oldest', limit: 1 }).items[0];
-}
-/** Lower pending selection for one recipient, oldest first. */
-export function pendingMessageHeads(facts, name, now = Date.now(), suppress = true) {
-    const endpoint = facts.endpoint(name);
-    if (endpoint === undefined || endpoint.attachment !== 'attached')
-        return [];
-    const heads = [];
-    let afterIndex = -1;
-    for (;;) {
-        const page = facts.directed(endpoint.participant, { afterIndex, unseenOnly: true, currentGeneration: true }, { edge: 'oldest', limit: 100 });
-        for (const head of page.items)
-            if (!suppress || !facts.suppressed(endpoint.participant, endpoint.generation, head.index, now))
-                heads.push(head);
-        if (!page.hasMore)
-            break;
-        afterIndex = page.items.at(-1).index;
-    }
-    return heads;
-}
-/** Lower recipients of one message that still owe a wake; other endpoints are untouched. */
-export function pendingAddresses(facts, index, now = Date.now()) {
-    return facts.addresses(index).flatMap(({ recipient, generation }) => {
-        const current = facts.endpoint(recipient);
-        if (current === undefined || current.attachment !== 'attached')
-            return [];
-        if (generation !== undefined && current.generation !== generation)
-            return [];
-        const head = pendingHeadAt(facts, recipient, index, now);
-        return head === undefined ? [] : [head];
-    });
-}

package/dist/channel-domain.d.ts

@@ -1,3 +0,0 @@
-import type { ChannelRead, ChannelWrite, ChannelWriteAuthority } from './channel-ports.js';
-/** Endpoint custody and operation authority without participant membership or social events. */
-export declare function wrapChannelWrite(read: ChannelRead, write: ChannelWrite, authority: ChannelWriteAuthority): ChannelWrite;

package/dist/channel-domain.js

@@ -1,83 +0,0 @@
-import { SquareError, validateOwner } from './neutral.js';
-import { sameName, validateName } from './channel-values.js';
-import { validateEndpointGeneration } from './message.js';
-/** Endpoint custody and operation authority without participant membership or social events. */
-export function wrapChannelWrite(read, write, authority) {
-    if (!authority || !['send', 'endpoint', 'endpoint-cleanup', 'participant'].includes(authority.kind))
-        throw new SquareError('invalid_args', 'Channel writes require an explicit authority.');
-    const name = authority.kind === 'send' ? authority.actor : authority.kind === 'endpoint' ? authority.participant : authority.seat.participant;
-    validateName(name);
-    if (authority.kind !== 'send')
-        validateOwner(authority.kind === 'endpoint' ? authority.owner : authority.seat.owner);
-    const fail = () => { throw new SquareError('already_joined', 'This operation needs its captured Channel endpoint.'); };
-    const captured = authority.kind === 'participant' || authority.kind === 'endpoint-cleanup' ? authority.seat : undefined;
-    if (captured)
-        validateEndpointGeneration(captured.generation);
-    function current(ref, allowDetached = false) {
-        const actual = read.endpoint(ref.participant);
-        if (!actual || !sameName(ref.participant, name) || actual.owner !== ref.owner || actual.generation !== ref.generation
-            || !allowDetached && actual.attachment !== 'attached')
-            fail();
-    }
-    function own(ref, allowDetached = false) {
-        if (authority.kind === 'endpoint') {
-            if (!sameName(ref.participant, name) || ref.owner !== authority.owner)
-                fail();
-        }
-        else if (!captured || !sameName(ref.participant, captured.participant) || ref.owner !== captured.owner || ref.generation !== captured.generation)
-            fail();
-        current(ref, allowDetached);
-    }
-    if (authority.kind === 'participant')
-        current(authority.seat);
-    const forbidden = () => { throw new SquareError('invalid_args', 'This Channel authority does not permit that mutation.'); };
-    const facts = Object.assign({}, read, Object.fromEntries(Object.keys(write)
-        .filter(key => !(key in read)).map(key => [key, forbidden])));
-    if (authority.kind === 'send' || authority.kind === 'participant') {
-        facts.publishMessage = draft => {
-            if (!sameName(draft.from, name))
-                fail();
-            if (captured)
-                current(captured);
-            return write.publishMessage(draft);
-        };
-    }
-    if (authority.kind === 'endpoint') {
-        facts.storeEndpoint = endpoint => {
-            if (!sameName(endpoint.participant, name) || endpoint.owner !== authority.owner)
-                fail();
-            return write.storeEndpoint(endpoint);
-        };
-        facts.reattachEndpoint = (ref, address) => { own(ref, true); return write.reattachEndpoint(ref, address); };
-    }
-    if (authority.kind === 'endpoint' || authority.kind === 'participant')
-        facts.updateWakeAddress = (ref, address) => { own(ref); return write.updateWakeAddress(ref, address); };
-    if (authority.kind === 'endpoint-cleanup') {
-        // Cleanup races are harmless; storage compares the captured owner and generation.
-        const cleanup = (ref) => {
-            if (!captured || !sameName(ref.participant, captured.participant) || ref.owner !== captured.owner || ref.generation !== captured.generation)
-                fail();
-        };
-        facts.detachEndpoint = ref => { cleanup(ref); return write.detachEndpoint(ref); };
-        facts.removeEndpoint = ref => { cleanup(ref); return write.removeEndpoint(ref); };
-    }
-    if (authority.kind === 'participant') {
-        facts.markSeen = (recipient, indexes, at) => { own({ ...authority.seat, participant: recipient }); return write.markSeen(recipient, indexes, at); };
-        facts.cancelThrough = (ref, through) => {
-            own(ref);
-            if (!Number.isSafeInteger(through) || through < 0 || through >= read.header().nextMessageIndex)
-                throw new SquareError('invalid_args', 'Cancellation boundary must be an assigned message index below the allocator.');
-            return write.cancelThrough(ref, through);
-        };
-        facts.claimDelivery = input => { own(input.seat); return write.claimDelivery(input); };
-        facts.prepareDelivery = input => { own(input.seat); return write.prepareDelivery(input); };
-        facts.completeDelivery = input => { own(input.seat); return write.completeDelivery(input); };
-        facts.observeNativeDelivery = input => { own(input.seat); return write.observeNativeDelivery(input); };
-        facts.putDeliveryDeferral = (ref, ...args) => { own(ref); return write.putDeliveryDeferral(ref, ...args); };
-        facts.renewDeliveryDeferral = (ref, ...args) => { own(ref); return write.renewDeliveryDeferral(ref, ...args); };
-        facts.releaseDeliveryDeferral = (ref, ...args) => { own(ref); return write.releaseDeliveryDeferral(ref, ...args); };
-        facts.putReceiveClaim = claim => { own({ ...authority.seat, participant: claim.owner, generation: claim.generation }); return write.putReceiveClaim(claim); };
-        facts.removeReceiveClaim = (owner, namespace, id) => { own({ ...authority.seat, participant: owner }); return write.removeReceiveClaim(owner, namespace, id); };
-    }
-    return facts;
-}

package/dist/channel-facade.d.ts

@@ -1,76 +0,0 @@
-import type { MessageMetadata } from './channel-values.js';
-import type { MetadataMatch } from './channel-metadata.js';
-import type { MessageId } from './message.js';
-export type ChannelTruncate = number | false;
-export interface ChannelSendInput {
-    readonly from: string;
-    readonly to: string | readonly string[];
-    readonly body: string;
-    readonly truncate?: ChannelTruncate;
-    readonly metadata?: MessageMetadata;
-}
-export interface ChannelSendResult {
-    readonly id: MessageId;
-    readonly at: number;
-    readonly from: string;
-    readonly to: readonly string[];
-    readonly body: string;
-    readonly metadata?: MessageMetadata;
-}
-export interface ChannelEndpointSummary {
-    readonly name: string;
-    readonly generation: string;
-    readonly attachment: 'attached' | 'detached';
-    readonly deliveryAvailable: boolean;
-    readonly unreadCount: number;
-    readonly lastActiveAt?: number;
-}
-export interface ChannelMessage {
-    readonly id: MessageId;
-    readonly at: number;
-    readonly from: string;
-    readonly to: readonly string[];
-    readonly body: string;
-    readonly metadata?: MessageMetadata;
-}
-export interface ChannelPendingResult {
-    readonly messages: readonly ChannelMessage[];
-    readonly remaining: number;
-}
-export interface MessageCursor {
-    readonly id: MessageId;
-    readonly direction: 'before' | 'after';
-}
-export interface MessageSearch {
-    readonly text: string;
-    readonly mode: 'literal' | 'regex';
-}
-export interface MessageQuery {
-    readonly at?: readonly MessageId[];
-    readonly from?: readonly string[];
-    readonly match?: MetadataMatch;
-    readonly search?: MessageSearch;
-    readonly cursor?: MessageCursor;
-}
-export interface ChannelHistoryQuery extends MessageQuery {
-    readonly limit?: number | null;
-    readonly order?: 'asc' | 'desc';
-}
-export interface ChannelPendingOptions extends MessageQuery {
-    readonly limit?: number;
-}
-export interface ChannelHistoryResult {
-    readonly messages: readonly ChannelMessage[];
-}
-export interface ChannelReceiveResult extends ChannelPendingResult {
-    readonly consumed: number;
-    readonly remaining: number;
-}
-export interface AckResult {
-    readonly consumed: number;
-}
-export interface ChannelEndpointHold {
-    readonly name: string;
-    readonly generation: string;
-    readonly attachment: 'attached' | 'detached';
-}

package/dist/channel-facade.js

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

package/dist/channel-internal.d.ts

@@ -1,126 +0,0 @@
-import { type MetadataMatch } from './delivery-deferral.js';
-import { type Owner } from './neutral.js';
-import { type WakeAddress } from './channel-values.js';
-import { type HarnessSessionChannel } from './participant-identity.js';
-import type { ChannelWriteAuthority, ChannelArtifact, EndpointFact, EndpointRef } from './channel-ports.js';
-import type { WakeTransportPort } from './channel-transport.js';
-import { validateEndpointGeneration, type MessageId } from './message.js';
-import type { AckResult, ChannelEndpointSummary, ChannelReceiveResult, ChannelPendingResult, ChannelHistoryResult, ChannelSendInput, ChannelSendResult, ChannelHistoryQuery, ChannelPendingOptions, ChannelEndpointHold } from './channel-facade.js';
-import type { DeliveryDeferral } from './delivery-deferral.js';
-import type { OperationControl, OperationFailureDetail } from './neutral.js';
-export { harnessOwner, decodeHarnessOwner, localUserOwner } from './owner.js';
-export type { MessageMetadata } from './channel-values.js';
-export type { MessageSearch, ChannelTruncate, ChannelPendingOptions, MessageCursor, MessageQuery, ChannelPendingResult, ChannelHistoryResult, ChannelHistoryQuery, AckResult, ChannelEndpointSummary, ChannelMessage, ChannelReceiveResult } from './channel-facade.js';
-export type { MessageId } from './message.js';
-export type { ChannelArtifact } from './channel-ports.js';
-export type { ChannelSendInput, ChannelSendResult, DeliveryDeferral, MetadataMatch, OperationControl, Owner, WakeAddress, WakeTransportPort, HarnessSessionChannel };
-export interface ResolvedHarnessSession {
-    readonly channel: HarnessSessionChannel;
-    readonly sessionId: string;
-    readonly agentId?: string;
-    readonly owner: Owner;
-    readonly wakeAddress?: WakeAddress;
-}
-export declare function resolveHarnessSession(env?: NodeJS.ProcessEnv): ResolvedHarnessSession | undefined;
-export interface ChannelOpenInput {
-    readonly path: string;
-    readonly cwd?: string;
-    readonly env?: NodeJS.ProcessEnv;
-    readonly clock?: () => number;
-    /** Transport for post-commit custody; `false` disables delivery for this handle. */
-    readonly wakeTransport?: WakeTransportPort | false;
-}
-export interface ChannelCreateInput extends ChannelOpenInput {
-    readonly force?: boolean;
-    readonly description?: string;
-}
-/** Every dependency one Channel needs; the artifact is already opened and narrowed. */
-export interface ChannelPortInit {
-    readonly location: string;
-    readonly artifact: ChannelArtifact;
-    readonly clock: () => number;
-    readonly deliverEffect?: (message?: number) => Promise<void>;
-    readonly indexPath?: string;
-    readonly closesArtifact?: boolean;
-}
-type EndpointOptions = {
-    readonly owner: Owner;
-    readonly wakeAddress?: WakeAddress;
-};
-export declare function checkControl(control?: OperationControl): void;
-export declare function squareClock(env: NodeJS.ProcessEnv, clock?: () => number): () => number;
-export declare function failure(error: unknown, detail: OperationFailureDetail): Error;
-/** Foundational point-to-point endpoint and messaging resource over one artifact port. */
-export declare class Channel {
-    readonly location: string;
-    readonly artifact: ChannelArtifact;
-    readonly clock: () => number;
-    private readonly deliverEffect?;
-    private readonly indexPath?;
-    private readonly closesArtifact;
-    private constructor();
-    /** Internal composition point for upper resources; no wrapping square is involved. */
-    static fromPort(init: ChannelPortInit): Channel;
-    static open(input: ChannelOpenInput, control?: OperationControl): Promise<Channel>;
-    static create(input: ChannelCreateInput, control?: OperationControl): Promise<Channel>;
-    static inMemory(input?: Omit<ChannelCreateInput, 'path' | 'force'>): Channel;
-    remember(owner: Owner): Promise<void>;
-    /** Establish a new opaque endpoint generation, or take over the existing one explicitly. */
-    attach(name: string, options: EndpointOptions & {
-        readonly takeover?: boolean;
-    }, control?: OperationControl): Promise<ChannelEndpoint>;
-    /** Restore an exact standing endpoint without changing its generation. */
-    reattach(name: string, { owner, wakeAddress }: Pick<EndpointOptions, 'owner' | 'wakeAddress'>, control?: OperationControl): Promise<ChannelEndpoint | null>;
-    private reattachEndpoint;
-    /** Select one attached endpoint held by an exact owner. */
-    endpoint(name: string, { owner }: {
-        readonly owner: Owner;
-    }): Promise<ChannelEndpoint>;
-    endpointsOf(owner: Owner): Promise<readonly ChannelEndpointHold[]>;
-    listEndpoints(control?: OperationControl): Promise<readonly ChannelEndpointSummary[]>;
-    detach(name: string, identity: {
-        readonly owner: Owner;
-        readonly generation: string;
-    }): Promise<true | null>;
-    cancelDeliveries(name: string, identity: {
-        readonly owner: Owner;
-        readonly generation: string;
-    }, control?: OperationControl): Promise<boolean>;
-    remove(name: string, identity: {
-        readonly owner: Owner;
-        readonly generation: string;
-    }): Promise<boolean>;
-    private held;
-    /** Commit one message, then run the shared custody runner outside the transaction. */
-    send(input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
-    sendAs(authority: ChannelWriteAuthority, input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
-    /** Shared post-commit custody runner. */
-    deliver(message?: number): Promise<void>;
-    history(query?: ChannelHistoryQuery, control?: OperationControl): Promise<ChannelHistoryResult>;
-    close(): Promise<void>;
-}
-/** Captures one recipient endpoint through the channel's own storage, never a wrapped square. */
-export declare class ChannelEndpoint {
-    private readonly channel;
-    private readonly endpointFact;
-    constructor(channel: Channel, endpointFact: EndpointFact);
-    get name(): string;
-    get generation(): string;
-    get ref(): EndpointRef;
-    private get storage();
-    private get participant();
-    pending(options?: ChannelPendingOptions, control?: OperationControl): Promise<ChannelPendingResult>;
-    ack(ids: readonly MessageId[], control?: OperationControl): Promise<AckResult>;
-    /** Select and consume matching unconsumed messages in one transaction. */
-    receive(options?: ChannelPendingOptions, control?: OperationControl): Promise<ChannelReceiveResult>;
-    deferDelivery(input: Readonly<{
-        match: MetadataMatch;
-        durationMs: number;
-    }>, control?: OperationControl): Promise<DeliveryDeferral>;
-    renewDeliveryDeferral(id: string, durationMs: number, control?: OperationControl): Promise<DeliveryDeferral | null>;
-    releaseDeliveryDeferral(id: string, control?: OperationControl): Promise<boolean>;
-    send(input: Omit<ChannelSendInput, 'from'>, control?: OperationControl): Promise<ChannelSendResult>;
-    /** Standalone Channel retirement; it ends no Agora membership. */
-    leave(control?: OperationControl): Promise<void>;
-}
-export { validateEndpointGeneration };