@aria-cli/tools 1.0.0

package/src/network-runtime/db-owner-fencing.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared database-level ownership fencing for runtime-owned durable stores.
+ *
+ * All stores backed by the same SQLite database share one `owner_epoch` table.
+ * The runtime claims the epoch once at startup. Each store's write methods
+ * call `assertDbOwnership()` before durable mutations.
+ *
+ * A zombie runtime whose generation is stale gets StaleOwnerError on
+ * its next write — no external kill needed.
+ */
+
+interface SqliteStatementLike {
+  run(...params: unknown[]): { changes: number };
+  get(...params: unknown[]): unknown;
+}
+
+export interface OwnerEpochDb {
+  exec(sql: string): unknown;
+  prepare(sql: string): SqliteStatementLike;
+}
+
+export class StaleOwnerError extends Error {
+  readonly kind = "StaleOwnerError" as const;
+  readonly claimedGeneration: number;
+  readonly currentGeneration: number;
+
+  constructor(claimed: number, current: number) {
+    super(
+      `StaleOwnerError: runtime claims generation ${claimed} but store is at generation ${current}. ` +
+        `This runtime has been superseded and must shut down immediately.`,
+    );
+    this.name = "StaleOwnerError";
+    this.claimedGeneration = claimed;
+    this.currentGeneration = current;
+  }
+}
+
+/**
+ * Ensure the owner_epoch table exists in the given database.
+ * Safe to call multiple times (idempotent).
+ */
+export function ensureOwnerEpochTable(db: OwnerEpochDb): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS owner_epoch (
+      scope TEXT PRIMARY KEY DEFAULT 'runtime',
+      owner_generation INTEGER NOT NULL
+    )
+  `);
+}
+
+/**
+ * Atomically claim the owner epoch for this runtime.
+ * Throws StaleOwnerError if a newer generation already owns the database.
+ */
+export function claimDbOwnerEpoch(db: OwnerEpochDb, generation: number): void {
+  ensureOwnerEpochTable(db);
+
+  const result = db
+    .prepare(
+      `INSERT INTO owner_epoch (scope, owner_generation) VALUES ('runtime', ?)
+       ON CONFLICT(scope) DO UPDATE SET owner_generation = excluded.owner_generation
+       WHERE excluded.owner_generation > owner_epoch.owner_generation`,
+    )
+    .run(generation);
+
+  if (result.changes === 0) {
+    const row = db
+      .prepare("SELECT owner_generation FROM owner_epoch WHERE scope = 'runtime'")
+      .get() as { owner_generation: number } | undefined;
+    const current = row?.owner_generation ?? 0;
+    if (current > generation) {
+      throw new StaleOwnerError(generation, current);
+    }
+  }
+}
+
+/**
+ * Assert the calling runtime is still the current owner of this database.
+ * Must be called inside the same SQLite transaction as the write.
+ * Throws StaleOwnerError if superseded.
+ */
+export function assertDbOwnership(db: OwnerEpochDb, generation: number): void {
+  const row = db
+    .prepare("SELECT owner_generation FROM owner_epoch WHERE scope = 'runtime'")
+    .get() as { owner_generation: number } | undefined;
+
+  const current = row?.owner_generation ?? 0;
+  if (current > generation) {
+    throw new StaleOwnerError(generation, current);
+  }
+}

package/src/network-runtime/delivery-receipts.ts

@@ -0,0 +1,372 @@
+import { z } from "zod";
+
+export const RuntimeTransportSchema = z.enum(["in_process", "local_runtime", "tunnel", "relay"]);
+export type RuntimeTransport = z.infer<typeof RuntimeTransportSchema>;
+
+export const DeliveryStateSchema = z.enum([
+  "accepted",
+  "queued_for_route",
+  "dispatching",
+  "sent",
+  "acked",
+  "expired",
+  "failed",
+  "rejected",
+]);
+export type DeliveryState = z.infer<typeof DeliveryStateSchema>;
+
+export const SessionStateSchema = z.enum(["none", "handshaking", "connected", "reconnecting", "dead"]);
+export type SessionState = z.infer<typeof SessionStateSchema>;
+
+export const DeliveryReadinessSchema = z.enum([
+  "cannot_address",
+  "can_queue_only",
+  "can_send_now",
+]);
+export type DeliveryReadiness = z.infer<typeof DeliveryReadinessSchema>;
+
+export const QueuedReasonSchema = z.enum([
+  "route_not_established",
+  "awaiting_remote_ack",
+  "transport_unavailable",
+]);
+export type QueuedReason = z.infer<typeof QueuedReasonSchema>;
+
+export const OutboxReceiptStatusSchema = z.enum([
+  "queued_for_route",
+  "dispatching",
+  "acked",
+  "expired",
+]);
+export type OutboxReceiptStatus = z.infer<typeof OutboxReceiptStatusSchema>;
+
+export const DeliveryReceiptInputSchema = z
+  .object({
+    transport: RuntimeTransportSchema,
+    delivered: z.boolean(),
+    queued: z.boolean(),
+    accepted: z.boolean().optional(),
+    deliveryState: DeliveryStateSchema.optional(),
+    sessionState: SessionStateSchema.optional(),
+    deliveryReadiness: DeliveryReadinessSchema.optional(),
+    queuedReason: QueuedReasonSchema.optional(),
+  })
+  .strict();
+
+export type DeliveryReceiptInput = z.input<typeof DeliveryReceiptInputSchema>;
+
+export interface CanonicalDeliveryReceipt {
+  transport: RuntimeTransport;
+  delivered: boolean;
+  queued: boolean;
+  accepted: boolean;
+  deliveryState: DeliveryState;
+  sessionState: SessionState;
+  deliveryReadiness: DeliveryReadiness;
+  queuedReason?: QueuedReason;
+}
+
+const DELIVERY_STATE_RESTRICTIVENESS: Record<DeliveryState, number> = {
+  rejected: 0,
+  failed: 1,
+  expired: 2,
+  queued_for_route: 3,
+  dispatching: 4,
+  accepted: 5,
+  sent: 6,
+  acked: 7,
+};
+
+const SESSION_STATE_RESTRICTIVENESS: Record<SessionState, number> = {
+  dead: 0,
+  none: 1,
+  handshaking: 2,
+  reconnecting: 3,
+  connected: 4,
+};
+
+const DELIVERY_READINESS_RESTRICTIVENESS: Record<DeliveryReadiness, number> = {
+  cannot_address: 0,
+  can_queue_only: 1,
+  can_send_now: 2,
+};
+
+function inferLegacyDeliveryState(input: DeliveryReceiptInput, accepted: boolean): DeliveryState {
+  if (!accepted) {
+    return input.deliveryState === "rejected" ? "rejected" : "failed";
+  }
+  if (input.delivered) {
+    return "acked";
+  }
+  if (input.queued) {
+    if (
+      input.queuedReason === "awaiting_remote_ack" ||
+      input.deliveryState === "dispatching" ||
+      input.deliveryState === "sent"
+    ) {
+      return "dispatching";
+    }
+    return "queued_for_route";
+  }
+  if (input.deliveryState === "expired") {
+    return "expired";
+  }
+  return "sent";
+}
+
+function normalizeExplicitDeliveryState(
+  input: DeliveryReceiptInput,
+): DeliveryState | undefined {
+  if (!input.deliveryState) {
+    return undefined;
+  }
+  if (
+    input.deliveryState === "sent" &&
+    input.queued &&
+    input.queuedReason === "awaiting_remote_ack"
+  ) {
+    return "dispatching";
+  }
+  return input.deliveryState;
+}
+
+function chooseMoreRestrictiveDeliveryState(
+  left: DeliveryState,
+  right: DeliveryState,
+): DeliveryState {
+  return DELIVERY_STATE_RESTRICTIVENESS[left] <= DELIVERY_STATE_RESTRICTIVENESS[right]
+    ? left
+    : right;
+}
+
+function inferSessionStateFromDeliveryState(
+  transport: RuntimeTransport,
+  deliveryState: DeliveryState,
+): SessionState {
+  if (transport === "local_runtime") {
+    return "none";
+  }
+  switch (deliveryState) {
+    case "queued_for_route":
+      return "handshaking";
+    case "dispatching":
+      return "connected";
+    case "failed":
+    case "rejected":
+    case "expired":
+      return "none";
+    case "acked":
+      return "connected";
+    case "accepted":
+    case "sent":
+      return "connected";
+    default:
+      return "none";
+  }
+}
+
+function chooseMoreRestrictiveSessionState(
+  transport: RuntimeTransport,
+  explicit: SessionState | undefined,
+  inferred: SessionState,
+): SessionState {
+  if (transport === "local_runtime") {
+    return "none";
+  }
+  if (!explicit) {
+    return inferred;
+  }
+  return SESSION_STATE_RESTRICTIVENESS[explicit] <= SESSION_STATE_RESTRICTIVENESS[inferred]
+    ? explicit
+    : inferred;
+}
+
+function inferDeliveryReadinessFromState(
+  transport: RuntimeTransport,
+  deliveryState: DeliveryState,
+  sessionState: SessionState,
+): DeliveryReadiness {
+  if (deliveryState === "failed" || deliveryState === "rejected") {
+    return "cannot_address";
+  }
+  if (transport === "local_runtime" && deliveryState === "acked") {
+    return "can_queue_only";
+  }
+  if (deliveryState === "queued_for_route") {
+    return "can_queue_only";
+  }
+  if (deliveryState === "dispatching") {
+    return sessionState === "reconnecting" ? "can_queue_only" : "can_send_now";
+  }
+  if (deliveryState === "expired") {
+    return "cannot_address";
+  }
+  return sessionState === "connected" ? "can_send_now" : "can_queue_only";
+}
+
+function chooseMoreRestrictiveDeliveryReadiness(
+  explicit: DeliveryReadiness | undefined,
+  inferred: DeliveryReadiness,
+): DeliveryReadiness {
+  if (!explicit) {
+    return inferred;
+  }
+  return DELIVERY_READINESS_RESTRICTIVENESS[explicit] <=
+    DELIVERY_READINESS_RESTRICTIVENESS[inferred]
+    ? explicit
+    : inferred;
+}
+
+function deriveCanonicalAccepted(
+  input: DeliveryReceiptInput,
+  deliveryState: DeliveryState,
+): boolean {
+  if (deliveryState === "rejected") {
+    return false;
+  }
+  return input.accepted ?? true;
+}
+
+function isQueuedDeliveryState(deliveryState: DeliveryState): boolean {
+  return deliveryState === "queued_for_route" || deliveryState === "dispatching";
+}
+
+function inferQueuedReason(
+  input: DeliveryReceiptInput,
+  deliveryState: DeliveryState,
+  queued: boolean,
+): QueuedReason | undefined {
+  if (!queued) {
+    return undefined;
+  }
+  if (input.queuedReason) {
+    return input.queuedReason;
+  }
+  if (deliveryState === "dispatching") {
+    return "awaiting_remote_ack";
+  }
+  if (deliveryState === "queued_for_route") {
+    return "route_not_established";
+  }
+  return undefined;
+}
+
+export function canonicalizeDeliveryReceipt(
+  input: DeliveryReceiptInput,
+): CanonicalDeliveryReceipt {
+  const inferredDeliveryState = inferLegacyDeliveryState(input, input.accepted ?? true);
+  const explicitDeliveryState = normalizeExplicitDeliveryState(input);
+  const deliveryState = explicitDeliveryState
+    ? chooseMoreRestrictiveDeliveryState(explicitDeliveryState, inferredDeliveryState)
+    : inferredDeliveryState;
+  const accepted = deriveCanonicalAccepted(input, deliveryState);
+  const delivered = deliveryState === "acked";
+  const queued = isQueuedDeliveryState(deliveryState);
+  const inferredSessionState = inferSessionStateFromDeliveryState(input.transport, deliveryState);
+  const sessionState = chooseMoreRestrictiveSessionState(
+    input.transport,
+    input.sessionState,
+    inferredSessionState,
+  );
+  const inferredDeliveryReadiness = inferDeliveryReadinessFromState(
+    input.transport,
+    deliveryState,
+    sessionState,
+  );
+  const deliveryReadiness = chooseMoreRestrictiveDeliveryReadiness(
+    input.deliveryReadiness,
+    inferredDeliveryReadiness,
+  );
+  const queuedReason = inferQueuedReason(input, deliveryState, queued);
+
+  return {
+    transport: input.transport,
+    delivered,
+    queued,
+    accepted,
+    deliveryState,
+    sessionState,
+    deliveryReadiness,
+    ...(queuedReason ? { queuedReason } : {}),
+  };
+}
+
+export function createAckedDeliveryReceipt(input: {
+  transport: RuntimeTransport;
+  sessionState?: SessionState;
+  deliveryReadiness?: DeliveryReadiness;
+}): CanonicalDeliveryReceipt {
+  return canonicalizeDeliveryReceipt({
+    transport: input.transport,
+    delivered: true,
+    queued: false,
+    accepted: true,
+    deliveryState: "acked",
+    ...(input.sessionState ? { sessionState: input.sessionState } : {}),
+    ...(input.deliveryReadiness ? { deliveryReadiness: input.deliveryReadiness } : {}),
+  });
+}
+
+export function createQueuedForRouteReceipt(input: {
+  transport: RuntimeTransport;
+  sessionState?: SessionState;
+  deliveryReadiness?: DeliveryReadiness;
+}): CanonicalDeliveryReceipt {
+  return canonicalizeDeliveryReceipt({
+    transport: input.transport,
+    delivered: false,
+    queued: true,
+    accepted: true,
+    deliveryState: "queued_for_route",
+    queuedReason: "route_not_established",
+    ...(input.sessionState ? { sessionState: input.sessionState } : {}),
+    ...(input.deliveryReadiness ? { deliveryReadiness: input.deliveryReadiness } : {}),
+  });
+}
+
+export function createDispatchingDeliveryReceipt(input: {
+  transport: RuntimeTransport;
+  sessionState?: SessionState;
+  deliveryReadiness?: DeliveryReadiness;
+}): CanonicalDeliveryReceipt {
+  return canonicalizeDeliveryReceipt({
+    transport: input.transport,
+    delivered: false,
+    queued: true,
+    accepted: true,
+    deliveryState: "dispatching",
+    queuedReason: "awaiting_remote_ack",
+    ...(input.sessionState ? { sessionState: input.sessionState } : {}),
+    ...(input.deliveryReadiness ? { deliveryReadiness: input.deliveryReadiness } : {}),
+  });
+}
+
+export function createSentDeliveryReceipt(input: {
+  transport: RuntimeTransport;
+  sessionState?: SessionState;
+  deliveryReadiness?: DeliveryReadiness;
+}): CanonicalDeliveryReceipt {
+  return canonicalizeDeliveryReceipt({
+    transport: input.transport,
+    delivered: false,
+    queued: false,
+    accepted: true,
+    deliveryState: "sent",
+    ...(input.sessionState ? { sessionState: input.sessionState } : {}),
+    ...(input.deliveryReadiness ? { deliveryReadiness: input.deliveryReadiness } : {}),
+  });
+}
+
+export function canonicalizeOutboxReceiptStatus(status: string): OutboxReceiptStatus {
+  switch (status) {
+    case "queued":
+    case "queued_for_route":
+      return "queued_for_route";
+    case "dispatching":
+    case "acked":
+    case "expired":
+      return status;
+    default:
+      throw new Error(`[delivery-receipts] Unsupported outbox status: ${status}`);
+  }
+}

package/src/network-runtime/direct-endpoint-authority.ts

@@ -0,0 +1,35 @@
+function normalizeHost(host: string): string {
+  return host.trim().toLowerCase();
+}
+
+export function isLoopbackDirectEndpointHost(host: string): boolean {
+  const normalized = normalizeHost(host);
+  return (
+    normalized === "localhost" ||
+    normalized === "::1" ||
+    normalized === "[::1]" ||
+    normalized.endsWith(".localhost") ||
+    /^127\./.test(normalized)
+  );
+}
+
+export function canonicalizeAuthoritativeDirectEndpoint(input: {
+  endpointHost?: string | null;
+  endpointPort?: number | null;
+}): {
+  endpointHost?: string;
+  endpointPort?: number;
+} {
+  const rawHost = input.endpointHost?.trim();
+  const port = input.endpointPort;
+  if (!rawHost || typeof port !== "number" || !Number.isFinite(port)) {
+    return {};
+  }
+  if (isLoopbackDirectEndpointHost(rawHost)) {
+    return {};
+  }
+  return {
+    endpointHost: rawHost,
+    endpointPort: port,
+  };
+}