@aeolus-fleet/core 0.0.0 → 0.18.0

package/dist/domain/messaging/mark-done.js

@@ -0,0 +1,49 @@
+import { holdLease } from '../registry/public.js';
+import { refuse } from '../shared/errors.js';
+import { recordEvent } from '../shared/events.js';
+import { ok } from '../shared/result.js';
+import { markDone } from './delivery.js';
+/**
+ * Marks a delivery to argo done inside the caller's unit of work, under the
+ * console session's lease, held until the unit of work ends: a sign-in
+ * elsewhere ending it waits, then returns nothing this marked. `reply` names
+ * the reply that made it done. Only argo: an agent acknowledges what it
+ * receives.
+ */
+export async function markDoneWithin(deps, done) {
+    const { tx, clock, ids } = deps;
+    const { crew, deliveryId, reply } = done;
+    if (crew.kind !== 'operator') {
+        return refuse('NOT_THE_OPERATOR_SHIP', 'Only argo marks a message done; a ship acknowledges what it receives');
+    }
+    const held = await holdLease(tx, crew);
+    if (!held.isOk) {
+        return held;
+    }
+    const delivery = await tx.deliveries.findForUpdate(crew.fleetId, deliveryId);
+    if (!delivery) {
+        return refuse('DELIVERY_NOT_FOUND', `Delivery ${deliveryId} does not exist`);
+    }
+    const marked = markDone(delivery, { crew, at: clock.now(), reply });
+    if (!marked.isOk) {
+        return marked;
+    }
+    const { delivery: changed, events } = marked.value;
+    if (events.length > 0) {
+        await tx.deliveries.update(changed);
+    }
+    for (const event of events) {
+        await recordEvent({ events: tx.events, ids }, event);
+    }
+    return ok(undefined);
+}
+/**
+ * Use case: argo marks a message to it done from the operator inbox, without
+ * a reply (docs/blueprint.md, "Inbox"). Its scope (messages:receive) is
+ * checked before this runs. One unit of work: the claim, the acknowledgement
+ * and their events.
+ */
+export function createMarkDone(deps) {
+    return (crew, input) => deps.uow.run((tx) => markDoneWithin({ tx, clock: deps.clock, ids: deps.ids }, { crew, deliveryId: input.deliveryId }));
+}
+//# sourceMappingURL=mark-done.js.map

package/dist/domain/messaging/mark-done.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mark-done.js","sourceRoot":"","sources":["../../../src/domain/messaging/mark-done.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAqC,MAAM,uBAAuB,CAAC;AAGrF,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAiB,MAAM,qBAAqB,CAAC;AACjE,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AAe/D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAwD,EACxD,IAA+D;IAE/D,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAChC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACzC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7B,OAAO,MAAM,CAAC,uBAAuB,EAAE,sEAAsE,CAAC,CAAC;IACjH,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAC7E,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,MAAM,CAAC,oBAAoB,EAAE,YAAY,UAAU,iBAAiB,CAAC,CAAC;IAC/E,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IACpE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC;IACnD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtC,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAqE;IAClG,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CACrB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,cAAc,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;AAC3H,CAAC"}

package/dist/domain/messaging/mark-read.d.ts

@@ -0,0 +1,27 @@
+import type { DeliveryId } from '@aeolus-fleet/common';
+import type { Crew } from '../shared/caller.js';
+import type { Clock } from '../shared/clock.js';
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+import type { UnitOfWork } from '../shared/unit-of-work.js';
+import type { DeliveryRepository } from './ports.js';
+export interface MarkReadTx {
+    deliveries: Pick<DeliveryRepository, 'findForUpdate' | 'markRead' | 'markUnread'>;
+}
+export type MarkReadRefusal = DomainError<'DELIVERY_NOT_FOUND' | 'NOT_THE_OPERATOR_SHIP'>;
+export type MarkRead = (crew: Crew, input: {
+    deliveryId: DeliveryId;
+    isRead: boolean;
+}) => Promise<Result<undefined, MarkReadRefusal>>;
+/**
+ * Use case: argo opens a message to it, which marks it read, or marks it
+ * unread again (docs/blueprint.md, "Inbox"). Its scope (messages:receive) is
+ * checked before this runs. Read is not done: the delivery's state stays as
+ * it is, and no event is written, since read is how the operator sees a
+ * message, not a step of its delivery. Opening it again keeps when it was
+ * first read. Done messages are read or unread too.
+ */
+export declare function createMarkRead(deps: {
+    uow: UnitOfWork<MarkReadTx>;
+    clock: Clock;
+}): MarkRead;

package/dist/domain/messaging/mark-read.js

@@ -0,0 +1,34 @@
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+import { isInInboxOf } from './delivery.js';
+/**
+ * Use case: argo opens a message to it, which marks it read, or marks it
+ * unread again (docs/blueprint.md, "Inbox"). Its scope (messages:receive) is
+ * checked before this runs. Read is not done: the delivery's state stays as
+ * it is, and no event is written, since read is how the operator sees a
+ * message, not a step of its delivery. Opening it again keeps when it was
+ * first read. Done messages are read or unread too.
+ */
+export function createMarkRead(deps) {
+    return async (crew, input) => {
+        if (crew.kind !== 'operator') {
+            return refuse('NOT_THE_OPERATOR_SHIP', 'Only argo marks a message read in the operator inbox');
+        }
+        return deps.uow.run(async (tx) => {
+            const { fleetId } = crew;
+            const { deliveryId } = input;
+            const delivery = await tx.deliveries.findForUpdate(fleetId, deliveryId);
+            if (!isInInboxOf(delivery, crew.shipId)) {
+                return refuse('DELIVERY_NOT_FOUND', `Delivery ${deliveryId} is not in your inbox`);
+            }
+            if (input.isRead) {
+                await tx.deliveries.markRead({ fleetId, deliveryId, at: deps.clock.now() });
+            }
+            else {
+                await tx.deliveries.markUnread({ fleetId, deliveryId });
+            }
+            return ok(undefined);
+        });
+    };
+}
+//# sourceMappingURL=mark-read.js.map

package/dist/domain/messaging/mark-read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mark-read.js","sourceRoot":"","sources":["../../../src/domain/messaging/mark-read.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAc5C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,IAAmD;IAChF,OAAO,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;QAC3B,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC7B,OAAO,MAAM,CAAC,uBAAuB,EAAE,sDAAsD,CAAC,CAAC;QACjG,CAAC;QACD,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAA+C,EAAE;YAC5E,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;YACzB,MAAM,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;YAC7B,MAAM,QAAQ,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;YACxE,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxC,OAAO,MAAM,CAAC,oBAAoB,EAAE,YAAY,UAAU,uBAAuB,CAAC,CAAC;YACrF,CAAC;YACD,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBACjB,MAAM,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC9E,CAAC;iBAAM,CAAC;gBACN,MAAM,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC;YAC1D,CAAC;YACD,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/domain/messaging/message.d.ts

@@ -0,0 +1,104 @@
+import { type DeliveryId, type DeliveryState, type FleetId, type LeaseId, type MessageId, type ShipId, type ShipKind } from '@aeolus-fleet/common';
+import { type DomainError } from '../shared/errors.js';
+import { type NewEvent } from '../shared/events.js';
+import { type Result } from '../shared/result.js';
+import type { Recipient } from '../shared/selector.js';
+/**
+ * An immutable envelope plus an opaque payload, sent by one ship to a
+ * selector (docs/blueprint.md, "Message"). Accepted only once its selector
+ * resolved to a ship that is not retired, or to a type with one.
+ */
+export interface Message {
+    id: MessageId;
+    fleetId: FleetId;
+    /** The calling ship: every sender is a ship, `argo` included. */
+    senderShipId: ShipId;
+    /** The selector as resolved at send time: a ship's id, never its name, or a type. */
+    selector: Recipient;
+    payload: string;
+    /** A media type, exactly as the sender gave it. */
+    contentType: string;
+    /** The model the sender's session stated it runs; none from argo, and none on messages from before models were stated. */
+    model: string | null;
+    /** Unique per sender: a repeat of the same request returns this message instead of storing a new one. */
+    idempotencyKey: string;
+    /** The hash of the request the message was sent with: what a repeat of its key must match. */
+    requestHash: string;
+    /** The message of the same fleet this one replies to. */
+    inReplyToMessageId: MessageId | null;
+    /** The message this one resends: an undeliverable one the operator sent again. */
+    resendOfMessageId: MessageId | null;
+    createdAt: Date;
+}
+/**
+ * One message to one resolved recipient, with its own state. Pending until a
+ * ship receives it; for a type, the first ship of that type to receive it
+ * claims it.
+ */
+export interface Delivery {
+    id: DeliveryId;
+    fleetId: FleetId;
+    messageId: MessageId;
+    recipient: Recipient;
+    state: DeliveryState;
+    /**
+     * The ship and the lease of the crew whose receive claimed it: set while it
+     * is in flight, kept once acknowledged, none while it is pending.
+     */
+    claimedByShipId: ShipId | null;
+    claimedByLeaseId: LeaseId | null;
+    /** How many times a receive claimed it. */
+    attempts: number;
+    createdAt: Date;
+}
+/** What the sender asked for, its payload and key already checked. */
+export interface MessageToAccept {
+    messageId: MessageId;
+    deliveryId: DeliveryId;
+    fleetId: FleetId;
+    senderShipId: ShipId;
+    payload: string;
+    contentType: string;
+    /** The model the sender states; a resend carries the original's. */
+    model: string | undefined;
+    /** Whether the sender is argo or an agent ship, for the model rule; a resend carries none, as it keeps the original's model. */
+    senderKind?: ShipKind;
+    idempotencyKey: string;
+    requestHash: string;
+    inReplyTo: MessageId | undefined;
+    /**
+     * For a resend: the message it resends and the ship that resent it, the
+     * operator. The sender stays the original one, so an answer goes back to
+     * whoever asked; the operator is the actor of MessageAccepted.
+     */
+    resendOf?: {
+        messageId: MessageId;
+        by: ShipId;
+    };
+    at: Date;
+}
+export type RepeatRefusal = DomainError<'IDEMPOTENCY_KEY_REUSED'>;
+/**
+ * A send with a key its sender used before. The same request is a repeat, a
+ * retry, and gets the original message's id; another request with that key is
+ * refused, so one key never stands for two messages.
+ */
+export declare function repeatOf(original: Message, requestHash: string): Result<MessageId, RepeatRefusal>;
+export type AcceptRefusal = DomainError<'IN_REPLY_TO_NOT_FOUND' | 'MODEL_REQUIRED' | 'MODEL_FROM_ARGO'>;
+/**
+ * Accepts a message: the message, its one pending delivery to the recipient
+ * its selector resolved to, and MessageAccepted, caused by the sender. A reply
+ * names a message of the same fleet: `repliedTo` is that message as the fleet
+ * holds it, if it does. Every ship but argo states the model its session
+ * runs (docs/blueprint.md, "Model"); argo states none. A resend carries the
+ * original message's model as it was, so it is not asked again; a ping is the
+ * fleet's question, not a session's message, so it carries none.
+ */
+export declare function acceptMessage(fleet: {
+    recipient: Recipient;
+    repliedTo: Message | undefined;
+}, send: MessageToAccept): Result<{
+    message: Message;
+    delivery: Delivery;
+    events: NewEvent[];
+}, AcceptRefusal>;

package/dist/domain/messaging/message.js

@@ -0,0 +1,84 @@
+import { isPingContentType } from '@aeolus-fleet/common';
+import { refuse } from '../shared/errors.js';
+import { shipActor } from '../shared/events.js';
+import { ok } from '../shared/result.js';
+/**
+ * A send with a key its sender used before. The same request is a repeat, a
+ * retry, and gets the original message's id; another request with that key is
+ * refused, so one key never stands for two messages.
+ */
+export function repeatOf(original, requestHash) {
+    return original.requestHash === requestHash
+        ? ok(original.id)
+        : refuse('IDEMPOTENCY_KEY_REUSED', 'This idempotency key was already used for another message: send a new message with a new key');
+}
+/**
+ * Accepts a message: the message, its one pending delivery to the recipient
+ * its selector resolved to, and MessageAccepted, caused by the sender. A reply
+ * names a message of the same fleet: `repliedTo` is that message as the fleet
+ * holds it, if it does. Every ship but argo states the model its session
+ * runs (docs/blueprint.md, "Model"); argo states none. A resend carries the
+ * original message's model as it was, so it is not asked again; a ping is the
+ * fleet's question, not a session's message, so it carries none.
+ */
+export function acceptMessage(fleet, send) {
+    const { recipient, repliedTo } = fleet;
+    const { messageId, deliveryId, fleetId, senderShipId, inReplyTo, resendOf, at } = send;
+    if (inReplyTo !== undefined && repliedTo?.id !== inReplyTo) {
+        return refuse('IN_REPLY_TO_NOT_FOUND', `Message ${inReplyTo} does not exist: a reply names a message of the fleet`);
+    }
+    const isStated = resendOf === undefined && !isPingContentType(send.contentType);
+    if (isStated && send.senderKind === 'operator' && send.model !== undefined) {
+        return refuse('MODEL_FROM_ARGO', 'argo states no model: send without one');
+    }
+    if (isStated && send.senderKind !== 'operator' && send.model === undefined) {
+        return refuse('MODEL_REQUIRED', 'send needs model: the exact model id this session runs, such as claude-opus-5-5');
+    }
+    const message = {
+        id: messageId,
+        fleetId,
+        senderShipId,
+        selector: recipient,
+        payload: send.payload,
+        contentType: send.contentType,
+        model: send.model ?? null,
+        idempotencyKey: send.idempotencyKey,
+        requestHash: send.requestHash,
+        inReplyToMessageId: inReplyTo ?? null,
+        resendOfMessageId: resendOf?.messageId ?? null,
+        createdAt: at,
+    };
+    const delivery = {
+        id: deliveryId,
+        fleetId,
+        messageId,
+        recipient,
+        state: 'pending',
+        claimedByShipId: null,
+        claimedByLeaseId: null,
+        attempts: 0,
+        createdAt: at,
+    };
+    return ok({
+        message,
+        delivery,
+        events: [
+            {
+                fleetId,
+                type: 'MessageAccepted',
+                occurredAt: at,
+                actor: shipActor(resendOf?.by ?? senderShipId),
+                shipId: recipient.kind === 'ship' ? recipient.shipId : undefined,
+                messageId,
+                deliveryId,
+                details: {
+                    selector: recipient.kind,
+                    recipientType: recipient.kind === 'type' ? recipient.type : null,
+                    model: send.model ?? null,
+                    ...(resendOf && { resendOf: resendOf.messageId }),
+                },
+            },
+        ],
+    });
+}
+//# sourceMappingURL=message.js.map

package/dist/domain/messaging/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../../../src/domain/messaging/message.ts"],"names":[],"mappings":"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"}

package/dist/domain/messaging/payload.d.ts

@@ -0,0 +1,9 @@
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+/**
+ * A message's payload: text, opaque to the fleet, which never reads, parses or
+ * changes it. At most 64 KB serialized, counted in UTF-8 bytes (ADR 0006): a
+ * message carries a reference and an instruction, not the content itself. The
+ * rule is shared with the common schema, so the door checks the same thing.
+ */
+export declare function payload(text: string): Result<string, DomainError<'PAYLOAD_TOO_LARGE'>>;

package/dist/domain/messaging/payload.js

@@ -0,0 +1,16 @@
+import { PAYLOAD_MAX_BYTES, payloadBytes } from '@aeolus-fleet/common';
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+/**
+ * A message's payload: text, opaque to the fleet, which never reads, parses or
+ * changes it. At most 64 KB serialized, counted in UTF-8 bytes (ADR 0006): a
+ * message carries a reference and an instruction, not the content itself. The
+ * rule is shared with the common schema, so the door checks the same thing.
+ */
+export function payload(text) {
+    const bytes = payloadBytes(text);
+    return bytes <= PAYLOAD_MAX_BYTES
+        ? ok(text)
+        : refuse('PAYLOAD_TOO_LARGE', `A payload is at most ${PAYLOAD_MAX_BYTES} bytes (64 KB) in UTF-8, not ${bytes}`);
+}
+//# sourceMappingURL=payload.js.map

package/dist/domain/messaging/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../../src/domain/messaging/payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEvE,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAEtD;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,KAAK,IAAI,iBAAiB;QAC/B,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC;QACV,CAAC,CAAC,MAAM,CAAC,mBAAmB,EAAE,wBAAwB,iBAAiB,gCAAgC,KAAK,EAAE,CAAC,CAAC;AACpH,CAAC"}

package/dist/domain/messaging/ping-ship.d.ts

@@ -0,0 +1,38 @@
+import { type IdGenerator, type MessageId, type ShipId } from '@aeolus-fleet/common';
+import { type PingableShipTx, type UnpingableShip } from '../registry/public.js';
+import type { Caller } from '../shared/caller.js';
+import type { Clock } from '../shared/clock.js';
+import { type Result } from '../shared/result.js';
+import type { UnitOfWork } from '../shared/unit-of-work.js';
+import type { RequestHasher } from './ports.js';
+import { type SendMessageRefusal, type SendMessageTx } from './send-message.js';
+/** What every ping says: the session answers it with pong, and does nothing else with it. */
+export declare const PING_PAYLOAD = "Ping from argo: answer with pong(deliveryId).";
+export type PingShipTx = SendMessageTx & PingableShipTx;
+export interface PingSent {
+    /** The ship's open ping: the one this call sent, or the one already waiting. */
+    messageId: MessageId;
+    sentAt: Date;
+    /** Whether this call sent it. */
+    isNew: boolean;
+}
+export type PingShipRefusal = UnpingableShip | SendMessageRefusal;
+export type PingShip = (caller: Caller, input: {
+    shipId: ShipId;
+}) => Promise<Result<PingSent, PingShipRefusal>>;
+/**
+ * Use case: argo pings a crewed ship (`fleet.ping`), asking its session to
+ * answer with pong. Its scope (fleet:manage) is checked before this runs. A
+ * ping is a message with the reserved content type and a fixed payload, sent
+ * and delivered as any message is. At most one is open per ship: while one
+ * waits unanswered, pending or in flight, this answers with that one and
+ * stores nothing. The ship stays locked meanwhile, so two pings take turns.
+ * Each new ping carries a fresh idempotency key: a repeat is answered by the
+ * open ping, never by the key.
+ */
+export declare function createPingShip(deps: {
+    uow: UnitOfWork<PingShipTx>;
+    clock: Clock;
+    ids: IdGenerator;
+    hasher: RequestHasher;
+}): PingShip;

package/dist/domain/messaging/ping-ship.js

@@ -0,0 +1,42 @@
+import { PING_CONTENT_TYPE } from '@aeolus-fleet/common';
+import { findPingableShip } from '../registry/public.js';
+import { ok } from '../shared/result.js';
+import { checkedSend, sendWithin } from './send-message.js';
+/** What every ping says: the session answers it with pong, and does nothing else with it. */
+export const PING_PAYLOAD = 'Ping from argo: answer with pong(deliveryId).';
+/**
+ * Use case: argo pings a crewed ship (`fleet.ping`), asking its session to
+ * answer with pong. Its scope (fleet:manage) is checked before this runs. A
+ * ping is a message with the reserved content type and a fixed payload, sent
+ * and delivered as any message is. At most one is open per ship: while one
+ * waits unanswered, pending or in flight, this answers with that one and
+ * stores nothing. The ship stays locked meanwhile, so two pings take turns.
+ * Each new ping carries a fresh idempotency key: a repeat is answered by the
+ * open ping, never by the key.
+ */
+export function createPingShip(deps) {
+    return (caller, input) => deps.uow.run(async (tx) => {
+        const { fleetId } = caller;
+        const ship = await findPingableShip(tx, { fleetId, shipId: input.shipId });
+        if (!ship.isOk) {
+            return ship;
+        }
+        const open = await tx.deliveries.findOpenPing(fleetId, input.shipId);
+        if (open) {
+            return ok({ messageId: open.id, sentAt: open.createdAt, isNew: false });
+        }
+        const request = checkedSend({
+            selector: { kind: 'ship', shipId: input.shipId },
+            payload: PING_PAYLOAD,
+            contentType: PING_CONTENT_TYPE,
+            idempotencyKey: `ping-${deps.ids('message')}`,
+        }, deps.hasher);
+        if (!request.isOk) {
+            return request;
+        }
+        const sentAt = deps.clock.now();
+        const sent = await sendWithin({ tx, clock: { now: () => sentAt }, ids: deps.ids }, { caller, request: request.value });
+        return sent.isOk ? ok({ messageId: sent.value.messageId, sentAt, isNew: true }) : sent;
+    });
+}
+//# sourceMappingURL=ping-ship.js.map

package/dist/domain/messaging/ping-ship.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ping-ship.js","sourceRoot":"","sources":["../../../src/domain/messaging/ping-ship.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAiD,MAAM,sBAAsB,CAAC;AAExG,OAAO,EAAE,gBAAgB,EAA4C,MAAM,uBAAuB,CAAC;AAGnG,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,WAAW,EAAE,UAAU,EAA+C,MAAM,mBAAmB,CAAC;AAEzG,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAG,+CAA+C,CAAC;AAgB5E;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAK9B;IACC,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CACvB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,EAA8C,EAAE;QACpE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,gBAAgB,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACrE,IAAI,IAAI,EAAE,CAAC;YACT,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1E,CAAC;QAED,MAAM,OAAO,GAAG,WAAW,CACzB;YACE,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE;YAChD,OAAO,EAAE,YAAY;YACrB,WAAW,EAAE,iBAAiB;YAC9B,cAAc,EAAE,QAAQ,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;SAC9C,EACD,IAAI,CAAC,MAAM,CACZ,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClB,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QAChC,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACvH,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzF,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/domain/messaging/ports.d.ts

@@ -0,0 +1,116 @@
+import type { DeliveryId, FleetId, LeaseId, MessageId, ShipId } from '@aeolus-fleet/common';
+import type { Delivery, Message } from './message.js';
+/** One sender's idempotency key, in its fleet. */
+export interface SenderKey {
+    fleetId: FleetId;
+    senderShipId: ShipId;
+    idempotencyKey: string;
+}
+/** Outbound port: messages, always within one fleet. Never changed once stored. */
+export interface MessageRepository {
+    create(message: Message): Promise<void>;
+    /**
+     * Holds the lock on the sender's idempotency key until the unit of work
+     * ends, so two sends with one key never both find it unused: the second
+     * waits, then finds the first one's message. Taken before anything else a
+     * send locks.
+     */
+    lockIdempotencyKey(key: SenderKey): Promise<void>;
+    /** The message the sender stored with this key, if any. */
+    findByIdempotencyKey(key: SenderKey): Promise<Message | undefined>;
+    find(fleetId: FleetId, messageId: MessageId): Promise<Message | undefined>;
+    /**
+     * Holds the fleet's daily message-count lock until the unit of work ends, so
+     * two sends at the daily limit never both see room for one more.
+     */
+    lockDailyCount(fleetId: FleetId): Promise<void>;
+    /** How many messages the fleet stored at or after `since`, of any kind and from any sender. */
+    countCreatedSince(fleetId: FleetId, since: Date): Promise<number>;
+}
+/**
+ * Outbound port: hashes a send's request text (SHA-256). The message keeps the
+ * hash, so a repeat of its key is told from a reuse without storing the
+ * request twice.
+ */
+export interface RequestHasher {
+    hash(request: string): string;
+}
+/** Which deliveries a crew may claim, and at most how many. */
+export interface ClaimableDeliveries {
+    fleetId: FleetId;
+    /** The crew's ship, and its type: deliveries pending for either are the crew's to claim. */
+    shipId: ShipId;
+    type: string;
+    /** The crew's lease: deliveries in flight with it are returned again. */
+    leaseId: LeaseId;
+    limit: number;
+    /** Deliveries this receive has already claimed, left out. */
+    excluding: readonly DeliveryId[];
+}
+/** A delivery a crew may claim, with the message it carries. */
+export interface ClaimableDelivery {
+    delivery: Delivery;
+    message: Message;
+}
+/** Outbound port: deliveries, always within one fleet. */
+export interface DeliveryRepository {
+    create(delivery: Delivery): Promise<void>;
+    /**
+     * Up to `limit` deliveries the crew may claim, each with its message: first
+     * those in flight with the crew's lease, then those pending for its ship or
+     * its type, oldest first within each. Each is locked until the unit of work
+     * ends, and one that another unit of work holds is skipped, never waited
+     * for: two receivers never get the same delivery (ADR 0003).
+     */
+    findClaimableForUpdate(query: ClaimableDeliveries): Promise<ClaimableDelivery[]>;
+    /**
+     * How many deliveries the crew's next receive would hand it: those in
+     * flight with its lease, and those pending for its ship or its type. Locks
+     * nothing and claims nothing.
+     */
+    countReceivable(query: Omit<ClaimableDeliveries, 'limit' | 'excluding'>): Promise<number>;
+    /** The delivery, locked until the unit of work ends. */
+    findForUpdate(fleetId: FleetId, deliveryId: DeliveryId): Promise<Delivery | undefined>;
+    /**
+     * The ping to the ship whose delivery is still open, pending or in flight:
+     * at most one, since pings never stack. Locks nothing: a ping holds the ship.
+     */
+    findOpenPing(fleetId: FleetId, shipId: ShipId): Promise<Message | undefined>;
+    /** Stores the delivery's state, its claim and its attempts. */
+    update(delivery: Delivery): Promise<void>;
+    /**
+     * Records that the delivery's recipient read it at `at`, keeping an earlier
+     * read: read is how the operator sees a message, not a delivery state.
+     */
+    markRead(read: {
+        fleetId: FleetId;
+        deliveryId: DeliveryId;
+        at: Date;
+    }): Promise<void>;
+    /** Forgets that the delivery was read: unread again. */
+    markUnread(read: {
+        fleetId: FleetId;
+        deliveryId: DeliveryId;
+    }): Promise<void>;
+}
+/** Where a waiting receive listens: its ship, and the queue of its type, in its fleet. */
+export interface ReceiverAddress {
+    fleetId: FleetId;
+    shipId: ShipId;
+    type: string;
+}
+/**
+ * Outbound port: wakes a waiting receive when a delivery may be pending for its
+ * ship or its type. A wake-up is a hint to look again, never a delivery: the
+ * receive finds out in the database whether one is there for it.
+ */
+export interface ReceiverWakeups {
+    /** Starts watching. A wake-up that comes before the next wait is kept for it. */
+    watch(address: ReceiverAddress): ReceiverWatch;
+}
+export interface ReceiverWatch {
+    /** Settles when the receive is woken, or once `waitMs` has passed. */
+    next(waitMs: number): Promise<'woken' | 'timedOut'>;
+    /** Stops watching. */
+    stop(): void;
+}

package/dist/domain/messaging/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map

package/dist/domain/messaging/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../../../src/domain/messaging/ports.ts"],"names":[],"mappings":""}

package/dist/domain/messaging/receive-deliveries.d.ts

@@ -0,0 +1,68 @@
+import type { DeliveryId, IdGenerator, MessageId, ShipId } from '@aeolus-fleet/common';
+import { type HoldLeaseTx, type LeaseEnded } from '../registry/public.js';
+import type { Crew } from '../shared/caller.js';
+import type { Clock } from '../shared/clock.js';
+import type { DomainError } from '../shared/errors.js';
+import { type EventLog } from '../shared/events.js';
+import { type Result } from '../shared/result.js';
+import type { Recipient } from '../shared/selector.js';
+import type { UnitOfWork } from '../shared/unit-of-work.js';
+import type { DeliveryRepository, ReceiverWakeups } from './ports.js';
+export interface ReceiveDeliveriesTx extends HoldLeaseTx {
+    deliveries: DeliveryRepository;
+    events: EventLog;
+}
+/** One delivery handed to the crew, with its message. */
+export interface ReceivedDelivery {
+    deliveryId: DeliveryId;
+    messageId: MessageId;
+    senderShipId: ShipId;
+    /** The sender's name and type as they are now, so the crew can answer it by name. */
+    senderName: string;
+    senderType: string;
+    /** Who the delivery is for: the crew's ship, or its type. */
+    recipient: Recipient;
+    payload: string;
+    contentType: string;
+    /** The model the sender's session stated; none from argo. */
+    model: string | null;
+    inReplyTo: MessageId | null;
+    sentAt: Date;
+    /** How many times the delivery has been claimed, this time included. */
+    attempts: number;
+}
+export interface DeliveriesReceived {
+    /** None when the wait ended without a delivery. */
+    deliveries: ReceivedDelivery[];
+}
+export type ReceiveRefusal = DomainError<'INVALID_RECEIVE_MAX' | 'SHIP_NOT_FOUND'> | LeaseEnded;
+export type ReceiveDeliveries = (crew: Crew, input: {
+    max?: number;
+}) => Promise<Result<DeliveriesReceived, ReceiveRefusal>>;
+/** How long a receive waits for a delivery when none is there: about 25 seconds, then it returns empty. */
+export declare const RECEIVE_WAIT_MS = 25000;
+/**
+ * Use case: a crew receives its deliveries (`receive`), up to `max`, 1 to 10,
+ * one by default. Its scope (messages:receive) is checked before this runs.
+ * Each attempt is one unit of work (see `claimForCrew`): every delivery it
+ * returns is in flight, claimed by the crew's ship and lease, until the ship
+ * acknowledges it or the lease ends, and the crew's next receive returns it
+ * again, counted as another claim, so a lost reply loses nothing. Its fifth
+ * claim makes it undeliverable instead. Each delivery names its sender by id,
+ * and by the name and type the sender has now, so the crew can answer by name.
+ *
+ * When nothing is there it waits, about 25 seconds, for a wake-up for its ship
+ * or its type (ADR 0003: LISTEN/NOTIFY after commit), then returns empty. It
+ * starts watching before it looks a second time, so a delivery that commits
+ * between its first look and its watch is found by that second look. A
+ * wake-up that brings nothing for it, a type delivery another ship took,
+ * leaves it waiting for the rest of its time.
+ */
+export declare function createReceiveDeliveries(deps: {
+    uow: UnitOfWork<ReceiveDeliveriesTx>;
+    clock: Clock;
+    ids: IdGenerator;
+    wakeups: ReceiverWakeups;
+    /** How long a receive waits on an empty inbox; about 25 seconds unless a test says otherwise. */
+    waitMs?: number;
+}): ReceiveDeliveries;