@namzu/sdk 38.0.0 → 38.2.1

package/dist/manager/resident/learning.js

@@ -0,0 +1,263 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { reviewHarnessCandidate, } from '../../eval/harness-verification.js';
+const label = z.string().trim().min(1).max(256);
+const name = z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/);
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+export const residentLearningEvidenceSchema = z.object({
+    key: label,
+    source: label,
+    reason: z.string().trim().min(1).max(1_000),
+});
+const candidateSchema = z.object({
+    name,
+    description: z.string().trim().min(1).max(1_000),
+    body: z.string().trim().min(1).max(4_000),
+});
+const learnedSkillSchema = candidateSchema.extend({
+    hash: digest,
+    evidence: residentLearningEvidenceSchema,
+    verification: z.object({
+        baselineHash: z.union([digest, z.literal('none')]),
+        candidateHash: digest,
+        evidenceDigest: digest,
+        verificationTasks: z.number().int().min(5).max(64),
+        confirmationTasks: z.number().int().min(5).max(64),
+    }),
+});
+export const residentLearningSchema = z
+    .object({
+    revision: z.number().int().positive().safe(),
+    identity: z
+        .object({
+        text: z.string().trim().min(1).max(4_000),
+        evidence: residentLearningEvidenceSchema,
+    })
+        .optional(),
+    preferences: z
+        .array(z.object({
+        key: name,
+        value: z.string().trim().min(1).max(1_000),
+        evidence: residentLearningEvidenceSchema,
+    }))
+        .max(32),
+    skills: z.array(learnedSkillSchema).max(16),
+    lastChange: residentLearningEvidenceSchema,
+})
+    .superRefine((state, context) => {
+    if (new Set(state.preferences.map((p) => p.key)).size !== state.preferences.length ||
+        new Set(state.skills.map((s) => s.name)).size !== state.skills.length ||
+        state.skills.some((skill) => skill.hash !== hashResidentSkill(skill) ||
+            skill.verification.candidateHash !== skill.hash))
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Invalid resident learning identity or content digest.',
+        });
+});
+/** Internal immutable snapshot used by storage and admitted context. */
+export function freezeResidentLearning(input) {
+    const state = residentLearningSchema.parse(input);
+    return Object.freeze({
+        ...state,
+        ...(state.identity
+            ? {
+                identity: Object.freeze({
+                    ...state.identity,
+                    evidence: Object.freeze(state.identity.evidence),
+                }),
+            }
+            : {}),
+        preferences: Object.freeze(state.preferences.map((p) => Object.freeze({ ...p, evidence: Object.freeze(p.evidence) }))),
+        skills: Object.freeze(state.skills.map((skill) => Object.freeze({
+            ...skill,
+            evidence: Object.freeze(skill.evidence),
+            verification: Object.freeze(skill.verification),
+        }))),
+        lastChange: Object.freeze(state.lastChange),
+    });
+}
+function evidenceFor(current, input) {
+    const evidence = residentLearningEvidenceSchema.parse(input);
+    const used = [
+        current?.lastChange,
+        current?.identity?.evidence,
+        ...(current?.preferences.map((p) => p.evidence) ?? []),
+        ...(current?.skills.map((s) => s.evidence) ?? []),
+    ];
+    if (used.some((old) => old?.key === evidence.key))
+        throw new Error('A learning change requires a fresh evidence key.');
+    return evidence;
+}
+function base(current, evidence) {
+    const checked = current ? freezeResidentLearning(current) : undefined;
+    return {
+        ...checked,
+        revision: (checked?.revision ?? 0) + 1,
+        preferences: checked?.preferences ?? [],
+        skills: checked?.skills ?? [],
+        lastChange: evidence,
+    };
+}
+/** Internal pure profile transition; storage owns exact agenda CAS and idle admission. */
+export function reviseResidentProfile(current, input) {
+    const checked = z
+        .object({
+        identity: z.string().trim().min(1).max(4_000).optional(),
+        preferences: z
+            .array(z.object({
+            key: name,
+            value: z.string().trim().min(1).max(1_000),
+            supersedes: label.nullable(),
+        }))
+            .max(32)
+            .optional(),
+        evidence: residentLearningEvidenceSchema,
+    })
+        .parse(input);
+    if (checked.identity === undefined && !checked.preferences?.length)
+        throw new Error('A profile change must change identity or preferences.');
+    if (new Set(checked.preferences?.map((p) => p.key)).size !== checked.preferences?.length &&
+        checked.preferences !== undefined)
+        throw new Error('Duplicate preference corrections are not allowed.');
+    const evidence = evidenceFor(current, checked.evidence);
+    const next = base(current, evidence);
+    const preferences = [...next.preferences];
+    for (const change of checked.preferences ?? []) {
+        const index = preferences.findIndex((p) => p.key === change.key);
+        const previous = index >= 0 ? preferences[index] : undefined;
+        if (change.supersedes !== (previous?.evidence.key ?? null))
+            throw new Error('Preference correction does not supersede its current evidence.');
+        const updated = { key: change.key, value: change.value, evidence };
+        if (index < 0)
+            preferences.push(updated);
+        else
+            preferences[index] = updated;
+    }
+    return freezeResidentLearning({
+        ...next,
+        preferences,
+        ...(checked.identity !== undefined ? { identity: { text: checked.identity, evidence } } : {}),
+    });
+}
+/** @experimental Bind evaluation to the exact normalized name, description and body. */
+export function hashResidentSkill(input) {
+    const candidate = candidateSchema.parse(input);
+    return createHash('sha256')
+        .update(JSON.stringify([candidate.name, candidate.description, candidate.body]))
+        .digest('hex');
+}
+/** Internal pure activation; reuse the kernel's conservative two-round verification gate. */
+export function promoteResidentSkill(current, input, evaluation, inputEvidence) {
+    const candidate = candidateSchema.parse(input);
+    const hash = hashResidentSkill(candidate);
+    const baselineHash = current?.skills.find((s) => s.name === candidate.name)?.hash ?? 'none';
+    const evidence = evidenceFor(current, inputEvidence);
+    for (const batch of [evaluation.verification, evaluation.confirmation]) {
+        if (!batch)
+            continue;
+        if (batch.baselineRevision !== baselineHash || batch.candidateRevision !== hash)
+            throw new Error('Skill evaluation does not match the active baseline and candidate digests.');
+        if (batch.baseline.length > 128 ||
+            batch.candidate.length > 128 ||
+            batch.attributions.length > 128)
+            throw new Error('Resident skill evaluation is bounded to 64 tasks per round.');
+        // Recorded evidence must consistently identify success and complete measurements.
+        for (const trial of [...batch.baseline, ...batch.candidate]) {
+            if (trial.result.passed !== (trial.result.status === 'passed') ||
+                (trial.result.status === 'passed' && trial.result.failedGates?.length))
+                throw new Error('Inconsistent recorded skill evaluation outcome.');
+        }
+    }
+    const review = reviewHarnessCandidate(evaluation.verification, evaluation.confirmation);
+    if (review.decision !== 'accept')
+        throw new Error(`Resident skill promotion ${review.decision}: ${review.reason}`);
+    const skill = {
+        ...candidate,
+        hash,
+        evidence,
+        verification: {
+            baselineHash,
+            candidateHash: hash,
+            evidenceDigest: createHash('sha256').update(JSON.stringify(evaluation)).digest('hex'),
+            verificationTasks: review.verification.tasks.length,
+            confirmationTasks: review.confirmation?.tasks.length ?? 0,
+        },
+    };
+    const next = base(current, evidence);
+    return freezeResidentLearning({
+        ...next,
+        skills: [...next.skills.filter((s) => s.name !== candidate.name), skill],
+    });
+}
+/** Internal rollback appends a new learning version while preserving current profile values. */
+export function restoreResidentSkill(current, historical, skillName, inputEvidence) {
+    name.parse(skillName);
+    if (!current?.skills.some((s) => s.name === skillName))
+        throw new Error('No active resident skill to roll back.');
+    const next = base(current, evidenceFor(current, inputEvidence));
+    const previous = historical
+        ? freezeResidentLearning(historical).skills.find((s) => s.name === skillName)
+        : undefined;
+    return freezeResidentLearning({
+        ...next,
+        skills: [...next.skills.filter((s) => s.name !== skillName), ...(previous ? [previous] : [])],
+    });
+}
+/** @experimental Bounded context data; never registers tools, loads files or executes a skill. */
+export function projectResidentLearning(current, options) {
+    if (!Number.isSafeInteger(options.maxChars) || options.maxChars < 0 || options.maxChars > 64_000)
+        throw new TypeError('Resident learning context requires maxChars between 0 and 64000.');
+    const selected = z.array(name).max(16).parse(options.skillNames);
+    if (new Set(selected).size !== selected.length)
+        throw new Error('Duplicate selected skill names.');
+    if (!current)
+        return Object.freeze({
+            text: '',
+            revision: null,
+            includedSkills: Object.freeze([]),
+            omitted: selected.length,
+        });
+    const state = freezeResidentLearning(current);
+    const pieces = [];
+    const includedSkills = [];
+    let omitted = 0;
+    let length = 0;
+    const add = (value) => {
+        const part = JSON.stringify(value);
+        const size = part.length + (pieces.length ? 1 : 0);
+        if (length + size > options.maxChars) {
+            omitted++;
+            return false;
+        }
+        pieces.push(part);
+        length += size;
+        return true;
+    };
+    if (state.identity)
+        add({ kind: 'self-description', ...state.identity });
+    for (const preference of state.preferences)
+        add({ kind: 'preference', ...preference });
+    for (const skillName of selected) {
+        const skill = state.skills.find((s) => s.name === skillName);
+        if (!skill) {
+            omitted++;
+            continue;
+        }
+        if (add({
+            kind: 'evaluated-guidance',
+            name: skill.name,
+            description: skill.description,
+            body: skill.body,
+            hash: skill.hash,
+            evidence: skill.evidence,
+        }))
+            includedSkills.push(skill.name);
+    }
+    return Object.freeze({
+        text: pieces.join('\n'),
+        revision: state.revision,
+        includedSkills: Object.freeze(includedSkills),
+        omitted,
+    });
+}
+//# sourceMappingURL=learning.js.map

package/dist/manager/resident/learning.js.map

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

package/dist/manager/resident/loop.d.ts

@@ -0,0 +1,31 @@
+import { type ResidentDecision, type ResidentExecutionStore, type ResidentState } from './store.js';
+/** @experimental Developer-owned step; bind providers, tools and budgets in the host. */
+export type ResidentStep = (state: ResidentState, signal: AbortSignal) => Promise<ResidentDecision>;
+/** @experimental No model is invoked for an idle, terminal or unresolved resident. */
+export type ResidentStepResult = {
+    status: 'settled';
+    state: ResidentState;
+} | {
+    status: 'idle';
+    reason: 'not-due' | 'terminal' | 'unresolved' | 'contended';
+    state: ResidentState;
+};
+/** @experimental A failed/aborted callback leaves its durable claim unresolved. */
+export declare function stepResident(store: ResidentExecutionStore, step: ResidentStep, signal: AbortSignal, now?: () => number): Promise<ResidentStepResult>;
+/** @experimental Bounded local driver; not a daemon, process recovery service or notification transport. */
+export interface ResidentLoopOptions {
+    readonly store: ResidentExecutionStore;
+    readonly step: ResidentStep;
+    readonly signal: AbortSignal;
+    /** Required finite admission cap for this invocation, independent of provider token limits. */
+    readonly maxSteps: number;
+    /** Maximum single idle wait, default 60 seconds. Longer waits return control to the host. */
+    readonly maxIdleMs?: number;
+}
+/**
+ * @experimental Continue a pursuit without a new user message. Null wake times
+ * and terminal states stop immediately; cancellation also interrupts idle waits.
+ * An abort cannot undo callback effects or forcibly stop a callback ignoring its signal.
+ */
+export declare function runResident(options: ResidentLoopOptions): Promise<ResidentStepResult>;
+//# sourceMappingURL=loop.d.ts.map

package/dist/manager/resident/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../../src/manager/resident/loop.ts"],"names":[],"mappings":"AACA,OAAO,EAEN,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,MAAM,YAAY,CAAA;AAEnB,yFAAyF;AACzF,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAEnG,sFAAsF;AACtF,MAAM,MAAM,kBAAkB,GAC3B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GAC3C;IACA,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,YAAY,GAAG,WAAW,CAAA;IAC3D,KAAK,EAAE,aAAa,CAAA;CACnB,CAAA;AAEJ,mFAAmF;AACnF,wBAAsB,YAAY,CACjC,KAAK,EAAE,sBAAsB,EAC7B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,WAAW,EACnB,GAAG,GAAE,MAAM,MAAiB,GAC1B,OAAO,CAAC,kBAAkB,CAAC,CA2B7B;AAED,4GAA4G;AAC5G,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAA;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA6B3F"}

package/dist/manager/resident/loop.js

@@ -0,0 +1,69 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { ResidentConflictError, } from './store.js';
+/** @experimental A failed/aborted callback leaves its durable claim unresolved. */
+export async function stepResident(store, step, signal, now = Date.now) {
+    signal.throwIfAborted();
+    const state = await store.read();
+    signal.throwIfAborted();
+    if (!state)
+        throw new Error('Create the resident before running it.');
+    if (state.phase === 'running')
+        return { status: 'idle', reason: 'unresolved', state };
+    if (state.phase !== 'waiting')
+        return { status: 'idle', reason: 'terminal', state };
+    if (state.wakeAt === null || state.wakeAt > now())
+        return { status: 'idle', reason: 'not-due', state };
+    let claim;
+    try {
+        claim = await store.claim(state, now());
+    }
+    catch (error) {
+        if (!(error instanceof ResidentConflictError))
+            throw error;
+        return {
+            status: 'idle',
+            reason: 'contended',
+            state: (await store.read()) ?? state,
+        };
+    }
+    signal.throwIfAborted();
+    const decision = await step(claim, signal);
+    signal.throwIfAborted();
+    return {
+        status: 'settled',
+        state: await store.settle(claim, decision, now()),
+    };
+}
+/**
+ * @experimental Continue a pursuit without a new user message. Null wake times
+ * and terminal states stop immediately; cancellation also interrupts idle waits.
+ * An abort cannot undo callback effects or forcibly stop a callback ignoring its signal.
+ */
+export async function runResident(options) {
+    const maxIdleMs = options.maxIdleMs ?? 60_000;
+    if (!Number.isSafeInteger(options.maxSteps) ||
+        options.maxSteps < 1 ||
+        !Number.isSafeInteger(maxIdleMs) ||
+        maxIdleMs < 0 ||
+        maxIdleMs > 2_147_483_647) {
+        throw new TypeError('Resident loop requires positive finite maxSteps and bounded nonnegative maxIdleMs.');
+    }
+    let admitted = 0;
+    while (true) {
+        const result = await stepResident(options.store, options.step, options.signal);
+        if (result.status === 'settled')
+            admitted++;
+        if (admitted >= options.maxSteps)
+            return result;
+        const { state } = result;
+        if (state.phase !== 'waiting' ||
+            state.wakeAt === null ||
+            (result.status === 'idle' && result.reason !== 'not-due'))
+            return result;
+        const delay = Math.max(0, state.wakeAt - Date.now());
+        if (delay > maxIdleMs)
+            return result;
+        await sleep(Math.max(1, delay), undefined, { signal: options.signal });
+    }
+}
+//# sourceMappingURL=loop.js.map

package/dist/manager/resident/loop.js.map

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

package/dist/manager/resident/outbox.d.ts

@@ -0,0 +1,180 @@
+import { z } from 'zod';
+import type { ResidentAgendaState } from './agenda.js';
+export declare const residentMessageInputSchema: z.ZodObject<{
+    id: z.ZodString;
+    pursuitId: z.ZodString;
+    destination: z.ZodString;
+    body: z.ZodEffects<z.ZodString, string, string>;
+    notBefore: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    body: string;
+    pursuitId: string;
+    destination: string;
+    notBefore: number;
+}, {
+    id: string;
+    body: string;
+    pursuitId: string;
+    destination: string;
+    notBefore: number;
+}>;
+/** @experimental Host-approved content and an opaque destination route, never credentials. */
+export type ResidentMessageInput = Readonly<z.infer<typeof residentMessageInputSchema>>;
+export declare const residentOutboxMessageSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    pursuitId: z.ZodString;
+    destination: z.ZodString;
+    body: z.ZodEffects<z.ZodString, string, string>;
+    notBefore: z.ZodNumber;
+} & {
+    tenantId: z.ZodString;
+    agentKey: z.ZodString;
+    sourceClaimId: z.ZodNullable<z.ZodString>;
+    revision: z.ZodNumber;
+    attempts: z.ZodNumber;
+    phase: z.ZodEnum<["pending", "sending", "acknowledged", "cancelled"]>;
+    claimId: z.ZodNullable<z.ZodString>;
+    nextAttemptAt: z.ZodNullable<z.ZodNumber>;
+    receiptId: z.ZodNullable<z.ZodString>;
+    acknowledgedAt: z.ZodNullable<z.ZodNumber>;
+    lastReason: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    revision: number;
+    attempts: number;
+    tenantId: string;
+    body: string;
+    phase: "pending" | "cancelled" | "sending" | "acknowledged";
+    agentKey: string;
+    pursuitId: string;
+    claimId: string | null;
+    destination: string;
+    notBefore: number;
+    sourceClaimId: string | null;
+    nextAttemptAt: number | null;
+    receiptId: string | null;
+    acknowledgedAt: number | null;
+    lastReason: string | null;
+}, {
+    id: string;
+    revision: number;
+    attempts: number;
+    tenantId: string;
+    body: string;
+    phase: "pending" | "cancelled" | "sending" | "acknowledged";
+    agentKey: string;
+    pursuitId: string;
+    claimId: string | null;
+    destination: string;
+    notBefore: number;
+    sourceClaimId: string | null;
+    nextAttemptAt: number | null;
+    receiptId: string | null;
+    acknowledgedAt: number | null;
+    lastReason: string | null;
+}>, {
+    id: string;
+    revision: number;
+    attempts: number;
+    tenantId: string;
+    body: string;
+    phase: "pending" | "cancelled" | "sending" | "acknowledged";
+    agentKey: string;
+    pursuitId: string;
+    claimId: string | null;
+    destination: string;
+    notBefore: number;
+    sourceClaimId: string | null;
+    nextAttemptAt: number | null;
+    receiptId: string | null;
+    acknowledgedAt: number | null;
+    lastReason: string | null;
+}, {
+    id: string;
+    revision: number;
+    attempts: number;
+    tenantId: string;
+    body: string;
+    phase: "pending" | "cancelled" | "sending" | "acknowledged";
+    agentKey: string;
+    pursuitId: string;
+    claimId: string | null;
+    destination: string;
+    notBefore: number;
+    sourceClaimId: string | null;
+    nextAttemptAt: number | null;
+    receiptId: string | null;
+    acknowledgedAt: number | null;
+    lastReason: string | null;
+}>;
+/** @experimental Acknowledgment proves transport acceptance, not human reading. */
+export type ResidentOutboxMessage = Readonly<z.infer<typeof residentOutboxMessageSchema>>;
+export declare const residentDeliveryOutcomeSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"acknowledged">;
+    receiptId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "acknowledged";
+    receiptId: string;
+}, {
+    kind: "acknowledged";
+    receiptId: string;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"not-accepted">;
+    retryAt: z.ZodNullable<z.ZodNumber>;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    kind: "not-accepted";
+    reason: string;
+    retryAt: number | null;
+}, {
+    kind: "not-accepted";
+    reason: string;
+    retryAt: number | null;
+}>]>;
+/** @experimental Retry only with evidence of non-acceptance; null retryAt ends delivery. */
+export type ResidentDeliveryOutcome = Readonly<z.infer<typeof residentDeliveryOutcomeSchema>>;
+/** @experimental Atomic admission and exact-claim settlement, without automatic claim expiry. */
+export interface ResidentOutboxStore {
+    read(): Promise<ResidentAgendaState | null>;
+    claimMessage(expected: ResidentAgendaState, id: string, now: number): Promise<ResidentOutboxMessage>;
+    settleMessage(expected: ResidentOutboxMessage, outcome: ResidentDeliveryOutcome, now: number): Promise<ResidentOutboxMessage>;
+}
+/** @experimental A synchronous host policy, evaluated before claiming and again before sending. */
+export type ResidentDeliveryGate = (message: ResidentOutboxMessage, now: number) => {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    readonly nextCheckAt: number | null;
+    readonly reason: string;
+};
+/** @experimental Bind an authorized route; forward message.id as the stable idempotency key. */
+export type ResidentMessageTransport = (message: ResidentOutboxMessage, signal: AbortSignal) => Promise<ResidentDeliveryOutcome>;
+/** @experimental One dispatch admission, with no model invocation, polling or implicit retries. */
+export interface ResidentDeliveryOptions {
+    readonly signal: AbortSignal;
+    readonly gate: ResidentDeliveryGate;
+    readonly now?: () => number;
+}
+/** @experimental An idle result never asserts a message reached its destination. */
+export type ResidentDeliveryResult = {
+    readonly status: 'settled';
+    readonly message: ResidentOutboxMessage;
+} | {
+    readonly status: 'idle';
+    readonly reason: 'paused' | 'unresolved' | 'empty' | 'not-due' | 'window' | 'contended';
+    readonly nextCheckAt: number | null;
+};
+/** Internal pure enqueue used in the same revision transaction as pursuit settlement. */
+export declare function appendResidentMessage(state: ResidentAgendaState, input: ResidentMessageInput, sourceClaimId?: string | null): readonly ResidentOutboxMessage[];
+/** Internal exact-message transition; agenda storage owns exclusive admission. */
+export declare function claimResidentOutboxMessage(message: ResidentOutboxMessage, now: number): ResidentOutboxMessage;
+/** Internal settlement; unknown failures deliberately have no transition. */
+export declare function settleResidentOutboxMessage(message: ResidentOutboxMessage, outcome: ResidentDeliveryOutcome, now: number): ResidentOutboxMessage;
+/**
+ * @experimental Persist one send claim before calling a host-owned transport.
+ * Throws, malformed outcomes and cancellation keep the claim unresolved. Stop
+ * old executors and inspect effects before explicit settleMessage reconciliation.
+ */
+export declare function deliverResidentMessage(store: ResidentOutboxStore, transport: ResidentMessageTransport, options: ResidentDeliveryOptions): Promise<ResidentDeliveryResult>;
+//# sourceMappingURL=outbox.d.ts.map

package/dist/manager/resident/outbox.d.ts.map

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