agent-embassy 1.0.0

package/dist/src/gateway/codex-registration-generation.js

@@ -0,0 +1,19 @@
+import { randomBytes } from "node:crypto";
+const CODEX_REGISTRATION_GENERATION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$/u;
+/** Closed grammar for opaque Codex listener and succession generations. */
+export function isCodexRegistrationGeneration(value) {
+    return (typeof value === "string" &&
+        CODEX_REGISTRATION_GENERATION_PATTERN.test(value));
+}
+export function assertCodexRegistrationGeneration(value, label = "Codex registration generation") {
+    if (!isCodexRegistrationGeneration(value)) {
+        throw new TypeError(`${label} must match the bounded opaque generation grammar.`);
+    }
+}
+/** A fresh 128-bit token that is safe in the closed generation grammar. */
+export function createCodexRegistrationGeneration() {
+    const generation = `g_${randomBytes(16).toString("base64url")}`;
+    assertCodexRegistrationGeneration(generation);
+    return generation;
+}
+//# sourceMappingURL=codex-registration-generation.js.map

package/dist/src/gateway/codex-registration-generation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-registration-generation.js","sourceRoot":"","sources":["../../../src/gateway/codex-registration-generation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,qCAAqC,GACzC,mCAAmC,CAAC;AAEtC,2EAA2E;AAC3E,MAAM,UAAU,6BAA6B,CAC3C,KAAc;IAEd,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,qCAAqC,CAAC,IAAI,CAAC,KAAK,CAAC,CAClD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iCAAiC,CAC/C,KAAc,EACd,KAAK,GAAG,+BAA+B;IAEvC,IAAI,CAAC,6BAA6B,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,oDAAoD,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,iCAAiC;IAC/C,MAAM,UAAU,GAAG,KAAK,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;IAChE,iCAAiC,CAAC,UAAU,CAAC,CAAC;IAC9C,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/src/gateway/codex-registration-succession.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Pure lifecycle for replacing one registered Codex task with another.
+ *
+ * The reducer owns no sockets, registry files, message bodies, conversations,
+ * timers, or provider clients. A controller executes the returned effects and
+ * feeds the resulting observations back as events. Listener generations are
+ * deliberately opaque; this module never derives a socket path or assumes a
+ * suffixed-socket naming scheme.
+ *
+ * Publication arming is the conservative irreversible boundary: the reducer
+ * enters it before emitting any durable-journal or registry-write effect.
+ * Cleanup may restore the old registration only before arming, or after a
+ * controller positively proves that neither the arm nor registry write was
+ * persisted. At or after any armed/published/unknown observation, the old
+ * registration can never be restored by this machine.
+ */
+export declare const codexRegistrationSuccessionPhases: readonly ["active_old", "freezing", "prepared_new", "published_new", "active_new", "offline_poisoned", "recovery_required", "resuming_old"];
+export type CodexRegistrationSuccessionPhase = (typeof codexRegistrationSuccessionPhases)[number];
+export type CodexRegistrationIdentity = Readonly<{
+    alias: string;
+    threadId: string;
+    hostId: string;
+    generation: string;
+}>;
+type StablePhase = "active_old" | "active_new";
+type FreezingStage = "barrier_pending" | "listener_pending" | "store_pending";
+type PublicationBoundary = "not_armed" | "armed_or_unknown" | "published";
+export declare const codexSuccessionFailurePhases: readonly ["freeze", "barrier", "listener", "store", "publication_arm", "registry", "activation", "retirement", "cleanup", "resume"];
+export type CodexSuccessionFailurePhase = (typeof codexSuccessionFailurePhases)[number];
+type SuccessionContext = Readonly<{
+    oldRegistration: CodexRegistrationIdentity;
+    newRegistration: CodexRegistrationIdentity;
+    priorStablePhase: StablePhase;
+}>;
+export type ActiveOldSuccessionState = Readonly<{
+    phase: "active_old";
+    active: CodexRegistrationIdentity;
+}>;
+export type ActiveNewSuccessionState = Readonly<{
+    phase: "active_new";
+    active: CodexRegistrationIdentity;
+    /** At most one prior listener generation may await confirmed retirement. */
+    retired: CodexRegistrationIdentity | null;
+}>;
+export type FreezingSuccessionState = SuccessionContext & Readonly<{
+    phase: "freezing";
+    stage: FreezingStage;
+}>;
+export type PreparedNewSuccessionState = SuccessionContext & Readonly<{
+    phase: "prepared_new";
+    /**
+     * `publication_arming` begins the rollback-forbidden window before the
+     * durable journal effect is executed. `registry_publishing` means the arm
+     * was confirmed and the registry write may be in flight.
+     */
+    stage: "publication_arming" | "registry_publishing";
+}>;
+export type PublishedNewSuccessionState = SuccessionContext & Readonly<{
+    phase: "published_new";
+}>;
+export type OfflinePoisonedSuccessionState = SuccessionContext & Readonly<{
+    phase: "offline_poisoned";
+    failedPhase: CodexSuccessionFailurePhase | "abort" | "barrier_busy";
+    safeErrorCode: string;
+    rollback: "old_allowed" | "forbidden";
+    publicationBoundary: PublicationBoundary;
+}>;
+export type RecoveryRequiredSuccessionState = SuccessionContext & Readonly<{
+    phase: "recovery_required";
+    failedPhase: CodexSuccessionFailurePhase | "abort" | "barrier_busy";
+    safeErrorCode: string;
+    rollback: "old_allowed" | "forbidden";
+    publicationBoundary: PublicationBoundary;
+}>;
+export type ResumingOldSuccessionState = SuccessionContext & Readonly<{
+    phase: "resuming_old";
+    failedPhase: CodexSuccessionFailurePhase | "abort" | "barrier_busy";
+    safeErrorCode: string;
+}>;
+export type CodexRegistrationSuccessionState = ActiveOldSuccessionState | ActiveNewSuccessionState | FreezingSuccessionState | PreparedNewSuccessionState | PublishedNewSuccessionState | OfflinePoisonedSuccessionState | RecoveryRequiredSuccessionState | ResumingOldSuccessionState;
+type CorrelatedEvent = Readonly<{
+    generation: string;
+}>;
+export type CodexRegistrationSuccessionEvent = Readonly<{
+    type: "begin";
+    registration: CodexRegistrationIdentity;
+}> | (CorrelatedEvent & Readonly<{
+    type: "barrier_clean";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "barrier_busy";
+    safeErrorCode: string;
+}>) | (CorrelatedEvent & Readonly<{
+    type: "listener_prepared";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "store_prepared";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "publication_armed";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "publication_absence_confirmed";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "registry_published";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "activate";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "cleanup_confirmed";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "resume_confirmed";
+}>) | (CorrelatedEvent & Readonly<{
+    type: "abort";
+    safeErrorCode: string;
+}>) | (CorrelatedEvent & Readonly<{
+    type: "phase_failed";
+    phase: CodexSuccessionFailurePhase;
+    safeErrorCode: string;
+}>) | (CorrelatedEvent & Readonly<{
+    type: "restart_evidence";
+    publication: "absent" | "armed" | "published" | "unknown";
+    safeErrorCode: string;
+}>);
+export type CodexRegistrationSuccessionEffect = Readonly<{
+    type: "freeze_old_ingress";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "freeze_old_dispatch";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "quiesce_and_join_old";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "verify_full_barrier";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "create_fresh_listener_generation";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "purge_old_conversations";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "purge_old_reply_capabilities";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "prepare_new_store";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    /**
+     * Persist the irreversible publication intent. The controller must
+     * durably save the returned `publication_arming` machine state before
+     * executing this effect.
+     */
+    type: "arm_publication_journal";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "publish_new_registry";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "activate_new_registration";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "retire_old_generation";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "close_old_listener";
+    registration: CodexRegistrationIdentity;
+    /**
+     * Registry cleanup is a generation-owned compare-and-delete. It may
+     * unlink only the retired record and must preserve the active record.
+     */
+    registryUnlink: Readonly<{
+        onlyIfOwnedGeneration: string;
+        protectedActiveGeneration: string;
+    }>;
+}> | Readonly<{
+    type: "cleanup_unpublished_generation";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "resume_old_ingress";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "resume_old_dispatch";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "poison_new_generation";
+    registration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "take_registrations_offline";
+    oldRegistration: CodexRegistrationIdentity;
+    newRegistration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "cleanup_poisoned_generations";
+    oldRegistration: CodexRegistrationIdentity;
+    newRegistration: CodexRegistrationIdentity;
+}> | Readonly<{
+    type: "manual_recovery_required";
+    registration: CodexRegistrationIdentity;
+    safeErrorCode: string;
+}>;
+export type CodexRegistrationSuccessionTransition = Readonly<{
+    state: CodexRegistrationSuccessionState;
+    effects: readonly CodexRegistrationSuccessionEffect[];
+}>;
+export declare function createCodexRegistrationSuccession(active: CodexRegistrationIdentity): ActiveOldSuccessionState;
+export declare function transitionCodexRegistrationSuccession(state: CodexRegistrationSuccessionState, event: CodexRegistrationSuccessionEvent): CodexRegistrationSuccessionTransition;
+/**
+ * Runtime assertion for controller boundaries and exhaustive state-machine
+ * tests. It intentionally validates identities without interpreting their
+ * opaque generation strings.
+ */
+export declare function assertCodexRegistrationSuccessionInvariant(state: CodexRegistrationSuccessionState): void;
+export {};