@cotal-ai/manager 0.16.0 → 0.18.0

package/dist/session/establish.d.ts

@@ -0,0 +1,212 @@
+/**
+ * The manager-side session ESTABLISHMENT (P2 item 6): mint the holder/target-lifecycle/
+ * instance+epoch-bound OFFER, and enforce its ONE-USE redemption through the §13.6 composite.
+ *
+ * Item 6 owns the offer mint + the STATIC redeem enforcement (this module) + the PTY bridge + the
+ * CLI/console clients + restart termination. The auth-service USER-MODE redemption handler
+ * (callout-minted per-session credentials) and the barrier session reconciler
+ * (implementations/auth/src/service.ts:358) are the #29 auth-trigger slice — OUT of item 6. This
+ * module exposes both halves through ONE {@link RedemptionSeam} interface: {@link
+ * staticRedemptionSeam} (wired) and {@link userModeRedemptionSeam} (a loud refusal until #29 lands
+ * — a user-mode attach must fail, never silently degrade to the static path).
+ *
+ * TARGET BINDING: the §13.6 grant is a CLOSED schema (holder + serving only), so the attached
+ * agent's (name, lifecycleUid) is bound MANAGER-SIDE — recorded in the {@link ManagerSessionRegistry}
+ * keyed by the fresh sessionId at mint, and re-checked live before the bridge serves (a despawned
+ * or replaced target ends the session with `target-despawn`). The holder + serving signature
+ * binding already stops a foreign party from redeeming or serving; the registry adds the target
+ * lifecycle the pin requires without widening the core artifact.
+ */
+import type { NatsConnection } from "@nats-io/transport-node";
+import { type AnchorResolver, type EpGateState, type LifecycleGatePin, type SessionCredential, type SessionGrant, type SessionLedger, type SessionPresenter } from "@cotal-ai/core";
+/** The attached agent's incarnation coordinate — the "target lifecycle" the offer binds (pin 1). */
+export interface SessionTarget {
+    name: string;
+    lifecycleUid: string;
+}
+/** The item-6 attach offer: the signed §13.6 grant plus the manager-side target binding. The REPLY
+ *  to the caller carries the `grant` only (holder-bound, non-bearer — a leak releases nothing);
+ *  `target` stays server-side (the caller already named it in the attach request). */
+export interface AttachOffer {
+    grant: SessionGrant;
+    target: SessionTarget;
+}
+export interface MintAttachOfferArgs {
+    space: string;
+    /** The serving manager incarnation: its lifecycleUid + the current serve-gate epoch (item-3 seam
+     *  — the §13.1 endpoint gate epoch; a successor incarnation advancing it refuses old sessions). */
+    serving: {
+        instanceId: string;
+        epoch: number;
+    };
+    /** The redeeming caller's triple, taken from the authenticated attach request (ctx.subject.caller). */
+    holder: {
+        id: string;
+        lifecycleUid: string;
+        processEpoch: number;
+    };
+    /** The attached agent + its incarnation (the target-lifecycle binding, recorded server-side). */
+    target: SessionTarget;
+    /** The manager's `sessions`-role signer (its own key material; the matching public key is its
+     *  registered `sessions` trust anchor the redeem/verify path resolves). */
+    signer: {
+        keyId: string;
+        keyPair: {
+            sign(input: Uint8Array): Uint8Array;
+        };
+    };
+    /** Session lifetime (§13.6 live-class; bounds the whole session, not just a redeem window). */
+    ttlMs: number;
+    /** Max in-flight data frames per direction (bounded flow window). */
+    window?: number;
+    now?: number;
+}
+/** Mint an attach offer: a §13.6 session grant on the `manager` endpoint bound to the holder triple
+ *  + serving instance/epoch, paired with the manager-side target binding. Pure — signs + returns;
+ *  the manager records the offer in its {@link ManagerSessionRegistry}. */
+export declare function mintAttachOffer(args: MintAttachOfferArgs): AttachOffer;
+/** The redemption's serving-gate observation, carried WHOLE rather than as a bare revision.
+ *
+ *  The §13.1 fence has to tell two revision moves apart: a BARRIER (which must refuse) and another
+ *  sibling mint's identical-bytes commit touch (which must not — every per-session credential
+ *  serializes on this one gate key, so refusing on contention would fail live sessions for no
+ *  security reason). A revision alone cannot make that distinction, so the pin carries the gate
+ *  state its revision came from and the fence compares EVERY field of it. */
+export interface ServingGatePin extends LifecycleGatePin {
+    /** The observation the revision came from. Absent ONLY on an open mesh, where nothing is minted,
+     *  nothing is staged, and there is no gate to fence against; the stage refuses loudly if it is
+     *  ever missing on an auth mesh rather than staging unfenced. */
+    gate?: EpGateState;
+}
+/**
+ * The manager's per-session SERVING credential, injected because minting one needs the space auth
+ * and the §13.1 endpoint gate, which live on the Manager, not in this module.
+ *
+ * The four calls are the credential's whole life, in the order §13.6 requires: `mint` produces
+ * bytes that are NOT yet authority, `stage` writes the gate-checked §13.1 ledger row that makes
+ * them revocable, the redemption's finalize CAS is what promotes them, and `revoke` kills the row
+ * by name at the session's terminal. `open` is separate from `mint` on purpose: nothing connects
+ * until the session row is `active`.
+ */
+export interface SessionServing {
+    /** Mint the per-session serving credential: exact-subject for THIS session only, expiring no
+     *  later than the grant. Bytes only — no ledger row yet, so this confers nothing durable. */
+    mint(grant: SessionGrant): Promise<SessionCredential>;
+    /** Stage its §13.1 credential-ledger row into the serving instance's revocation family, fenced on
+     *  `pin` — the gate observed during THIS redemption, which stays the authority: the commit CASes
+     *  on its revision, and a lost CAS is refused unless the gate is still identical in every field
+     *  but the revision. MUST throw if the gate moved — that loss is the lifecycle fence, and a throw
+     *  here refuses the whole redemption. */
+    stage(grant: SessionGrant, cred: SessionCredential, pin: ServingGatePin): Promise<void>;
+    /** Open the serving connection for ONE session with that credential. MUST fail loud: there is no
+     *  shared connection to fall back to, and serving a session without its own credential is exactly
+     *  the standing-writer shape this design removes. */
+    open(cred: SessionCredential): Promise<NatsConnection>;
+    /** Revoke the credential by id, idempotently (§13.6 makes the sweep retry until the mark sticks).
+     *
+     *  RESIDUAL, NAMED: this marks the §13.1 ledger row revoked; it does NOT evict a live connection.
+     *  The session's own teardown closes its connection first, so in the ordinary path the credential
+     *  has no connection left to use — but if that close fails, the JWT stays broker-valid until its
+     *  TTL (bounded by the session exp). Cluster-verified eviction of these holders belongs to the
+     *  §13.1 takeover barrier, which enumerates the family. So: do not read this as immediate broker
+     *  death on session close. */
+    revoke(credentialId: string): Promise<void>;
+    /** LEADER-SERVED observation of the serving instance's §13.1 issuance gate, returned as the pin
+     *  {@link stage} is CASed against. Real, not a placeholder: it is what makes the stage a fence. */
+    observeGate(endpoint: string, instanceId: string): Promise<ServingGatePin>;
+}
+/** The one interface both modes present. `redeem` VERIFIES the presented grant (signature/anchor/
+ *  currency) then enforces the one-use CAS + presenter-equality; it THROWS on any refusal (a second
+ *  redeem, a foreign presenter, an expired/forged grant) and returns the sessionId on success.
+ *  `serving` then hands the SERVING party its own credential — a separate, authenticated retrieval
+ *  (§13.6 per-party release: no private material crosses between the two parties, so it is never
+ *  folded into the redemption answer). */
+export interface RedemptionSeam {
+    redeem(grant: SessionGrant, presenter: SessionPresenter): Promise<{
+        sessionId: string;
+    }>;
+    serving(sessionId: string, presenter: {
+        endpoint: string;
+        instanceId: string;
+        epoch: number;
+    }): Promise<SessionCredential>;
+}
+type MaybePromise<T> = T | Promise<T>;
+/** What {@link staticRedemptionSeam} reads from the manager's durable authority. In production the
+ *  ledger + gate/epoch reads come from the auth store (leader-served); the smoke supplies an
+ *  in-memory faithful ledger. */
+export interface StaticRedemptionDeps {
+    space: string;
+    resolveAnchor: AnchorResolver;
+    ledger: SessionLedger;
+    /** The per-session serving credential's mint/stage/open/revoke seam (see {@link SessionServing}). */
+    serving: SessionServing;
+    holderProcessEpoch(holder: {
+        id: string;
+        lifecycleUid: string;
+    }): MaybePromise<number | undefined>;
+    servingEpoch(endpoint: string, instanceId: string): MaybePromise<number | undefined>;
+    observeHolderGate(holder: {
+        id: string;
+        lifecycleUid: string;
+    }): MaybePromise<LifecycleGatePin>;
+    observeServingGate(endpoint: string, instanceId: string): MaybePromise<ServingGatePin>;
+    now?(): number;
+}
+/**
+ * The STATIC redeem seam (item 6's wired path): the manager runs the §13.6 redemption — verify the
+ * signed grant, then `redeemSession` (the one-use `issuing` create-CAS + presenter-equality + the
+ * gate-pinned stage + the finalize's fresh epoch re-checks) — and, for the SERVING half, mints,
+ * stages, releases and revokes a real per-session credential through {@link SessionServing}.
+ *
+ * WHAT EACH HALF ACTUALLY GETS, stated exactly, because the two halves are NOT symmetric here and a
+ * comment claiming they are would be worse than the asymmetry:
+ *
+ *  - SERVING half (this manager's own): a real `session-serving` credential, exact-subject
+ *    (`eps.<endpoint>.<sessionId>.<epoch>.{in,out}`), TTL-bound to the session, staged into this
+ *    instance's §13.1 `epcred.<endpoint>.<instanceId>` family under the open-and-commit fence, and
+ *    revoked BY NAME at the session's terminal. It replaces a STANDING wildcard credential that
+ *    reached every live session's bytes at its epoch (SPEC 13.9:2526).
+ *  - CALLER half: NOT minted, staged, or revoked here, and `releaseCredential` returns a MARKER with
+ *    no usable bytes for it. The caller's `session-caller` JWT is minted OUT OF BAND from the local
+ *    space seed — by the console establisher and by CLI attach — after redemption.
+ *
+ *    SPEC 13.6 PAIR-REVOKE IS NOT IMPLEMENTED FOR THE CALLER HALF. Stated exactly, because the
+ *    difference between this and pair-revoke is the whole residual: that JWT is not written into the
+ *    session lineage, is not named by the session row's credential material, and is untouched by
+ *    session close and by takeover reconcile. It dies by TTL alone, at a 24h ceiling
+ *    (`SESSION_GRANT_MAX_TTL_MS`).
+ *
+ *    Why the window is tolerable for THIS static slice, as reviewed: the caller grant is
+ *    exact-pinned to one `(endpoint, sessionId, epoch)`, so it can reach neither a sibling session
+ *    nor a successor epoch; and once the serving half is revoked and its connection closed there is
+ *    no counterparty on those two subjects. What survives is a broker-valid connection, not reach
+ *    into another session. Closing it properly means minting the caller half inside redemption,
+ *    which needs the user-mode (#29) callout exchange. Until that lands, do not describe any part of
+ *    this as pair teardown.
+ *  - `revokeCredential` is therefore ONE-SIDED by construction: it revokes an id this seam minted
+ *    and is an explicit no-op for the caller id, rather than silently appearing to revoke both.
+ */
+export declare function staticRedemptionSeam(deps: StaticRedemptionDeps): RedemptionSeam;
+/** The USER-MODE redeem seam: UNWIRED (the #29 auth-trigger slice owns the callout-minted
+ *  per-session credential path). It REFUSES LOUD, naming the path — a user-mode attach fails rather
+ *  than degrading to the static seam (item-6 binding no-fallback rule). */
+export declare function userModeRedemptionSeam(): RedemptionSeam;
+/** The manager's in-memory session registry: the sessionId → (target lifecycle, offer) binding the
+ *  §13.6 grant cannot carry. The serve path looks the target up here and re-checks its liveness
+ *  before bridging, so a despawned/replaced target ends the session (`target-despawn`). */
+export declare class ManagerSessionRegistry {
+    #private;
+    /** Record a freshly minted offer. Throws on a sessionId collision (a fresh unguessable id never
+     *  repeats — a repeat is a mint bug, never silently overwritten). */
+    record(offer: AttachOffer): void;
+    /** The target bound to a sessionId, or undefined if unknown/removed. */
+    target(sessionId: string): SessionTarget | undefined;
+    /** Drop a session (redeem-refused, closed, expired, or target gone). Idempotent. */
+    remove(sessionId: string): void;
+    /** Every sessionId whose target is a given agent incarnation — the set a despawn/restart must end. */
+    forTarget(name: string, lifecycleUid: string): string[];
+    get size(): number;
+}
+export {};
+//# sourceMappingURL=establish.d.ts.map

package/dist/session/establish.d.ts.map

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

package/dist/session/establish.js

@@ -0,0 +1,174 @@
+import { EpEnvelopeError, mintSessionGrant, redeemSession, retrieveServingCredential, verifySessionGrant, } from "@cotal-ai/core";
+import { MANAGER_ENDPOINT } from "../manager-service-contract.js";
+/** Mint an attach offer: a §13.6 session grant on the `manager` endpoint bound to the holder triple
+ *  + serving instance/epoch, paired with the manager-side target binding. Pure — signs + returns;
+ *  the manager records the offer in its {@link ManagerSessionRegistry}. */
+export function mintAttachOffer(args) {
+    const grant = mintSessionGrant({
+        space: args.space,
+        endpoint: MANAGER_ENDPOINT,
+        holder: args.holder,
+        serving: args.serving,
+        ttlMs: args.ttlMs,
+        ...(args.window !== undefined ? { window: args.window } : {}),
+        issuerKeyId: args.signer.keyId,
+        ...(args.now !== undefined ? { now: args.now } : {}),
+    }, args.signer.keyPair);
+    return { grant, target: { name: args.target.name, lifecycleUid: args.target.lifecycleUid } };
+}
+/**
+ * The STATIC redeem seam (item 6's wired path): the manager runs the §13.6 redemption — verify the
+ * signed grant, then `redeemSession` (the one-use `issuing` create-CAS + presenter-equality + the
+ * gate-pinned stage + the finalize's fresh epoch re-checks) — and, for the SERVING half, mints,
+ * stages, releases and revokes a real per-session credential through {@link SessionServing}.
+ *
+ * WHAT EACH HALF ACTUALLY GETS, stated exactly, because the two halves are NOT symmetric here and a
+ * comment claiming they are would be worse than the asymmetry:
+ *
+ *  - SERVING half (this manager's own): a real `session-serving` credential, exact-subject
+ *    (`eps.<endpoint>.<sessionId>.<epoch>.{in,out}`), TTL-bound to the session, staged into this
+ *    instance's §13.1 `epcred.<endpoint>.<instanceId>` family under the open-and-commit fence, and
+ *    revoked BY NAME at the session's terminal. It replaces a STANDING wildcard credential that
+ *    reached every live session's bytes at its epoch (SPEC 13.9:2526).
+ *  - CALLER half: NOT minted, staged, or revoked here, and `releaseCredential` returns a MARKER with
+ *    no usable bytes for it. The caller's `session-caller` JWT is minted OUT OF BAND from the local
+ *    space seed — by the console establisher and by CLI attach — after redemption.
+ *
+ *    SPEC 13.6 PAIR-REVOKE IS NOT IMPLEMENTED FOR THE CALLER HALF. Stated exactly, because the
+ *    difference between this and pair-revoke is the whole residual: that JWT is not written into the
+ *    session lineage, is not named by the session row's credential material, and is untouched by
+ *    session close and by takeover reconcile. It dies by TTL alone, at a 24h ceiling
+ *    (`SESSION_GRANT_MAX_TTL_MS`).
+ *
+ *    Why the window is tolerable for THIS static slice, as reviewed: the caller grant is
+ *    exact-pinned to one `(endpoint, sessionId, epoch)`, so it can reach neither a sibling session
+ *    nor a successor epoch; and once the serving half is revoked and its connection closed there is
+ *    no counterparty on those two subjects. What survives is a broker-valid connection, not reach
+ *    into another session. Closing it properly means minting the caller half inside redemption,
+ *    which needs the user-mode (#29) callout exchange. Until that lands, do not describe any part of
+ *    this as pair teardown.
+ *  - `revokeCredential` is therefore ONE-SIDED by construction: it revokes an id this seam minted
+ *    and is an explicit no-op for the caller id, rather than silently appearing to revoke both.
+ */
+export function staticRedemptionSeam(deps) {
+    // The minted-but-unreleased serving credential, held between `allocateCredentialIds` and
+    // `releaseCredential`. NAMED RESIDUAL: the JWT exists before the one-use create-CAS is won,
+    // because the credential id the `issuing` row must name IS its digest. If the create loses, the
+    // bytes are dropped here having never been staged, released, or connected with — they reach no
+    // other party and no ledger row was written for them.
+    const minted = new Map();
+    const callerId = (grant) => `${grant.sessionId}.c`;
+    const marker = async (sessionId, credentialId) => {
+        const row = await deps.ledger.read(sessionId);
+        if (!row)
+            throw new EpEnvelopeError("failed-precondition", `no session row for ${sessionId}; nothing releases without its authority row (SPEC 13.6)`);
+        return { id: credentialId, creds: "", exp: row.exp };
+    };
+    // The serving pin core observed for THIS redemption, kept so the stage fences on the WHOLE
+    // observation rather than the bare {key, revision} core's hook type carries. One seam is built per
+    // establishment, so this holds exactly one redemption's pin and cannot be crossed with another's.
+    let servingPin;
+    const hooks = {
+        ledger: deps.ledger,
+        holderProcessEpoch: (h) => deps.holderProcessEpoch(h),
+        servingEpoch: (e, i) => deps.servingEpoch(e, i),
+        observeHolderGate: (h) => deps.observeHolderGate(h),
+        observeServingGate: async (e, i) => {
+            servingPin = await deps.observeServingGate(e, i);
+            return servingPin;
+        },
+        allocateCredentialIds: async (grant) => {
+            const cred = await deps.serving.mint(grant);
+            minted.set(grant.sessionId, cred);
+            return { credCaller: callerId(grant), credServing: cred.id };
+        },
+        // The §13.1 fence for the half this manager owns: stage the serving credential's ledger row
+        // REVISION-PINNED to the serving gate observed moments ago. A barrier that moved the gate makes
+        // this LOSE and throw, and redeemSession turns that into a refusal that releases nothing.
+        stagePair: async (grant, ids, pins) => {
+            const cred = minted.get(grant.sessionId);
+            if (!cred || cred.id !== ids.credServing)
+                throw new EpEnvelopeError("internal", `no minted serving credential for session ${grant.sessionId}; the stage cannot pin a credential that was never minted (SPEC 13.6)`);
+            // The pin handed to the stage MUST be the one this seam observed. Core passes the observation
+            // through, so this is an identity re-check, not a conversion: if it ever failed we would be
+            // fencing against a gate nobody in this redemption read, which is worse than not staging.
+            if (!servingPin || servingPin.revision !== pins.serving.revision || servingPin.key !== pins.serving.key)
+                throw new EpEnvelopeError("internal", `the serving gate pin staged against is not the one this redemption observed for session ${grant.sessionId} (SPEC 13.1)`);
+            await deps.serving.stage(grant, cred, servingPin);
+        },
+        releaseCredential: async (sessionId, credentialId) => {
+            const cred = minted.get(sessionId);
+            // Idempotent for the row's life (§13.6 lost-response retry): the SAME bytes, never a re-mint.
+            if (cred && cred.id === credentialId)
+                return cred;
+            return marker(sessionId, credentialId); // the caller half: no bytes to hand back (see doc)
+        },
+        revokeCredential: async (id) => {
+            for (const [sessionId, cred] of minted) {
+                if (cred.id !== id)
+                    continue;
+                await deps.serving.revoke(id);
+                minted.delete(sessionId);
+                return;
+            }
+            // Not ours: the caller id, which this seam never minted and therefore cannot revoke.
+        },
+        ...(deps.now ? { now: deps.now } : {}),
+    };
+    return {
+        async redeem(grant, presenter) {
+            const now = deps.now?.() ?? Date.now();
+            const verified = await verifySessionGrant(grant, { space: deps.space, resolveAnchor: deps.resolveAnchor, now });
+            try {
+                await redeemSession(verified, presenter, hooks); // one-use CAS + presenter-equality (throws on refuse)
+            }
+            catch (e) {
+                minted.delete(verified.sessionId); // a refused redemption keeps no minted bytes
+                throw e;
+            }
+            return { sessionId: verified.sessionId };
+        },
+        serving: (sessionId, presenter) => retrieveServingCredential(sessionId, presenter, hooks),
+    };
+}
+/** The USER-MODE redeem seam: UNWIRED (the #29 auth-trigger slice owns the callout-minted
+ *  per-session credential path). It REFUSES LOUD, naming the path — a user-mode attach fails rather
+ *  than degrading to the static seam (item-6 binding no-fallback rule). */
+export function userModeRedemptionSeam() {
+    const refuse = () => Promise.reject(new EpEnvelopeError("unimplemented", "user-mode session redemption (callout-minted per-session credentials) is not wired in this build; " +
+        "it is the #29 auth-trigger slice. A user-mode attach fails loud rather than degrading (SPEC 13.6, item-6 no-fallback)."));
+    return { redeem: refuse, serving: refuse };
+}
+/** The manager's in-memory session registry: the sessionId → (target lifecycle, offer) binding the
+ *  §13.6 grant cannot carry. The serve path looks the target up here and re-checks its liveness
+ *  before bridging, so a despawned/replaced target ends the session (`target-despawn`). */
+export class ManagerSessionRegistry {
+    #byId = new Map();
+    /** Record a freshly minted offer. Throws on a sessionId collision (a fresh unguessable id never
+     *  repeats — a repeat is a mint bug, never silently overwritten). */
+    record(offer) {
+        if (this.#byId.has(offer.grant.sessionId))
+            throw new EpEnvelopeError("already-exists", `session ${offer.grant.sessionId} is already recorded; a fresh sessionId never repeats (SPEC 13.6)`);
+        this.#byId.set(offer.grant.sessionId, { target: offer.target, grant: offer.grant });
+    }
+    /** The target bound to a sessionId, or undefined if unknown/removed. */
+    target(sessionId) {
+        return this.#byId.get(sessionId)?.target;
+    }
+    /** Drop a session (redeem-refused, closed, expired, or target gone). Idempotent. */
+    remove(sessionId) {
+        this.#byId.delete(sessionId);
+    }
+    /** Every sessionId whose target is a given agent incarnation — the set a despawn/restart must end. */
+    forTarget(name, lifecycleUid) {
+        const out = [];
+        for (const [id, e] of this.#byId)
+            if (e.target.name === name && e.target.lifecycleUid === lifecycleUid)
+                out.push(id);
+        return out;
+    }
+    get size() {
+        return this.#byId.size;
+    }
+}
+//# sourceMappingURL=establish.js.map

package/dist/session/establish.js.map

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

package/dist/session/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * P2 item 6 — the manager's mesh-attach session plane: the offer mint + redeem enforcement, the
+ * PTY ↔ rail bridge, and the application framing over the core §13.6 session composite. The
+ * generic composite (grant/redeem/rails/ledger) lives in `@cotal-ai/core` +
+ * `implementations/auth`; this module is the manager-side CONSUMER that replaces the loopback
+ * `ws://127.0.0.1` attach face.
+ */
+export { mintAttachOffer, staticRedemptionSeam, userModeRedemptionSeam, ManagerSessionRegistry, type AttachOffer, type MintAttachOfferArgs, type SessionTarget, type RedemptionSeam, type SessionServing, type StaticRedemptionDeps, } from "./establish.js";
+export { serveSessionBridge, type ServeSessionBridgeOpts, type SessionBridge, type AttachEndReason } from "./bridge.js";
+export { ManagerSessionPlane, kvManagerSessionLedger, openSessionLedgerKv, MAX_LIVE_SESSIONS_DEFAULT, type ManagerSessionPlaneDeps, } from "./plane.js";
+export { encodeTerminalData, terminalFrameBytes, decodeTerminalFrame, type TerminalFrame } from "@cotal-ai/core";
+//# sourceMappingURL=index.d.ts.map

package/dist/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACxH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/session/index.js

@@ -0,0 +1,15 @@
+/**
+ * P2 item 6 — the manager's mesh-attach session plane: the offer mint + redeem enforcement, the
+ * PTY ↔ rail bridge, and the application framing over the core §13.6 session composite. The
+ * generic composite (grant/redeem/rails/ledger) lives in `@cotal-ai/core` +
+ * `implementations/auth`; this module is the manager-side CONSUMER that replaces the loopback
+ * `ws://127.0.0.1` attach face.
+ */
+export { mintAttachOffer, staticRedemptionSeam, userModeRedemptionSeam, ManagerSessionRegistry, } from "./establish.js";
+export { serveSessionBridge } from "./bridge.js";
+export { ManagerSessionPlane, kvManagerSessionLedger, openSessionLedgerKv, MAX_LIVE_SESSIONS_DEFAULT, } from "./plane.js";
+// The terminal-session frame codec is NORMATIVE WIRE and lives in core (the §13.6 terminal-session
+// profile); re-exported here for the manager's own consumers/smokes. The CLI + console import it
+// straight from @cotal-ai/core (implementations cannot import each other).
+export { encodeTerminalData, terminalFrameBytes, decodeTerminalFrame } from "@cotal-ai/core";
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,GAOvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAyE,MAAM,aAAa,CAAC;AACxH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,GAE1B,MAAM,YAAY,CAAC;AACpB,mGAAmG;AACnG,iGAAiG;AACjG,2EAA2E;AAC3E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAsB,MAAM,gBAAgB,CAAC"}

package/dist/session/plane.d.ts

@@ -0,0 +1,120 @@
+import type { KV } from "@nats-io/kv";
+import type { NatsConnection } from "@nats-io/transport-node";
+import { type AnchorResolver, type AttachSession, type SessionGrant, type SessionLedger } from "@cotal-ai/core";
+import { type SessionServing, type SessionTarget } from "./establish.js";
+import type { AttachEndReason } from "./bridge.js";
+/** A manager-local {@link SessionLedger} over `session.<id>` rows in the DEDICATED sessions bucket
+ *  KV (never the auth bucket — §13.9 subject-blindness confinement). Drives the SAME core row/key
+ *  types as implementations/auth's ledger with the manager's own KV CAS: the
+ *  one-use is `createIssuing`'s create-only CAS; finalize/terminal/revoke are revision-pinned
+ *  updates (a lost CAS returns false / retries on the next sweep, never a silent overwrite). */
+export declare function kvManagerSessionLedger(kv: KV): SessionLedger;
+/** The default global live-session ceiling. Configurable per manager
+ *  ({@link ManagerSessionPlaneDeps.maxSessions}) because the right number is deployment-shaped: the
+ *  browser console opens a session PER PANE, so a dashboard over a large mesh legitimately holds
+ *  many at once, and a ceiling low enough to feel like a bound would break it. */
+export declare const MAX_LIVE_SESSIONS_DEFAULT = 64;
+export interface ManagerSessionPlaneDeps {
+    space: string;
+    /** The serving manager incarnation — instanceId = the managerLifecycleUid, epoch = the serve grant epoch. */
+    serving: {
+        instanceId: string;
+        epoch: number;
+    };
+    /** The manager's `sessions`-role signer + the resolver that returns its matching anchor (the
+     *  manager self-signs and self-verifies its own offers). */
+    signer: {
+        keyId: string;
+        keyPair: {
+            sign(input: Uint8Array): Uint8Array;
+        };
+    };
+    resolveAnchor: AnchorResolver;
+    /** The DEDICATED sessions-bucket KV holding the `session.<id>` ledger rows (never the auth bucket). */
+    ledgerKv: KV;
+    /** The per-session SERVING credential seam: mint, gate-checked stage, connection open, revoke.
+     *  Injected because minting needs the space auth + the §13.1 gate, which live on the Manager. */
+    servingCredential: SessionServing;
+    /** Session lifetime (§13.6 live-class) + the bounded flow window. */
+    ttlMs: number;
+    window?: number;
+    /**
+     * Global ceiling on concurrently live sessions; defaults to {@link MAX_LIVE_SESSIONS_DEFAULT}.
+     *
+     * Redemption is caller-triggered and each session now mints a credential and opens a connection,
+     * so without a ceiling an authorized caller could drive both without bound. This is deliberately
+     * the plane's OWN bound rather than an inherited one: whatever route authz sits in front of
+     * establishment, the process-level resource limit is a number here that can be executed against.
+     *
+     * RESIDUAL, NAMED: the ceiling is GLOBAL, not per caller. It protects the process, which is what
+     * it is for, but it does not stop one authorized operator from exhausting it and denying sessions
+     * to another. That was accepted on the grounds that only authorized operators reach redemption at
+     * all — the attach face's console-token gate refuses before the establisher runs. If that gate is
+     * ever relaxed, weakened, or made optional, this scoping assumption goes with it and the ceiling
+     * needs a per-caller dimension.
+     */
+    maxSessions?: number;
+    now?(): number;
+}
+export declare class ManagerSessionPlane {
+    #private;
+    constructor(deps: ManagerSessionPlaneDeps);
+    /** Mint an offer for the authenticated attach caller, enforce its one-use redemption, and stand
+     *  up the PTY bridge — all atomically. Returns the HOLDER-BOUND grant (the attach reply): no URL,
+     *  and it must never be logged. Throws on a redeem refusal (a foreign presenter, an already-live
+     *  session, a stale serving epoch). */
+    establishAttach(caller: {
+        owner: string;
+        actor: string;
+        uid: string;
+    }, target: SessionTarget, session: AttachSession, 
+    /** A slot already claimed by an establisher in front of this one ({@link claimSlot}), so the
+     *  reservation covers ITS side effects too (the PTY attach above all). Omitted = claim here. */
+    claimed?: {
+        release(): void;
+    }): Promise<{
+        grant: SessionGrant;
+    }>;
+    /** End every session bound to a target incarnation, with a distinct reason — the despawn/restart
+     *  hook (the successor incarnation's differing epoch already refuses old-epoch redemptions; this
+     *  proactively tears the live bridges down and surfaces the reason to each client). The bridge's
+     *  own `onEnd` drives {@link #teardown}, so the connection and credential go with it. */
+    endForTarget(name: string, lifecycleUid: string, reason: AttachEndReason): void;
+    /** End all live sessions (manager stop / drain). */
+    endAll(reason: AttachEndReason): void;
+    /** Await every in-flight teardown (manager stop): the bridges' `onEnd` teardown is async, so a
+     *  synchronous `endAll` alone would let the process exit with connections still draining. */
+    drain(reason: AttachEndReason): Promise<void>;
+    get liveSessions(): number;
+    /** The configured global ceiling (surfaced so an operator-facing status can report it). */
+    get maxSessions(): number;
+    /**
+     * CLAIM a session slot, or refuse loudly. ONE implementation, called by {@link establishAttach}
+     * and by every establisher in front of it, so the two cannot drift into disagreeing about
+     * capacity. It must run before ANY of: minting the offer, redeeming it, minting a per-session
+     * credential on either side, opening a connection, or attaching the target's PTY.
+     *
+     * THIS RESERVES, IT DOES NOT MERELY CHECK. A bare read of the live count would be check-then-act:
+     * establishment awaits a mint, a redemption and a connection before the session becomes live, so
+     * two concurrent establishes at `max - 1` would both observe room, both mint credentials, and
+     * both land — overshooting the ceiling by exactly the concurrency the HTTP face already has, and
+     * over-minting the seed-signed credentials the ceiling exists to bound. Occupancy is therefore
+     * live sessions PLUS in-flight reservations, and the increment happens with no `await` between
+     * the read and the write, so on a single-threaded runtime no second establishment can interleave.
+     *
+     * The returned release is idempotent: the caller releases on every failure path, and
+     * {@link establishAttach} releases at the same instant it records the live session, so a slot is
+     * counted once and never twice.
+     *
+     * The message names the ceiling and its current value: an operator who hits it should not have to
+     * read source to learn which knob to raise.
+     */
+    claimSlot(): {
+        release(): void;
+    };
+}
+/** Open the DEDICATED sessions-bucket KV a plane's ledger needs (the `session.<id>` rows live in
+ *  the §13.6 session store — {@link sessionsBucket}, NOT the auth bucket). Split out so the manager
+ *  can build the plane from its own bucket handle. */
+export declare function openSessionLedgerKv(nc: NatsConnection, bucket: string): Promise<KV>;
+//# sourceMappingURL=plane.d.ts.map

package/dist/session/plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plane.d.ts","sourceRoot":"","sources":["../../src/session/plane.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,aAAa,EAElB,KAAK,YAAY,EACjB,KAAK,aAAa,EAGnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAiE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAExI,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD;;;;gGAIgG;AAChG,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,EAAE,GAAG,aAAa,CA4C5D;AAED;;;kFAGkF;AAClF,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,6GAA6G;IAC7G,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;gEAC4D;IAC5D,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE;YAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAA;SAAE,CAAA;KAAE,CAAC;IAC5E,aAAa,EAAE,cAAc,CAAC;IAC9B,uGAAuG;IACvG,QAAQ,EAAE,EAAE,CAAC;IACb;qGACiG;IACjG,iBAAiB,EAAE,cAAc,CAAC;IAClC,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,IAAI,MAAM,CAAC;CAChB;AAUD,qBAAa,mBAAmB;;gBASlB,IAAI,EAAE,uBAAuB;IAQzC;;;2CAGuC;IACjC,eAAe,CACnB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EACrD,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa;IACtB;oGACgG;IAChG,OAAO,CAAC,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,GAC5B,OAAO,CAAC;QAAE,KAAK,EAAE,YAAY,CAAA;KAAE,CAAC;IA0HnC;;;6FAGyF;IACzF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAI/E,oDAAoD;IACpD,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAIrC;iGAC6F;IACvF,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,2FAA2F;IAC3F,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,IAAI;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE;CAUjC;AAED;;sDAEsD;AACtD,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC,CAEzF"}