@namzu/sdk 42.0.2 → 44.0.0

package/dist/manager/run/persistence.d.ts

@@ -1,312 +0,0 @@
-import type { TokenBudget } from '../../run/token-budget.js';
-import { type CostInfo, type TokenUsage } from '../../types/common/index.js';
-import type { RunId, SessionId, TenantId } from '../../types/ids/index.js';
-import type { Message } from '../../types/message/index.js';
-import type { ProviderErrorInfo } from '../../types/provider/index.js';
-import type { AuditEvent, AuditEventInput } from '../../types/run/audit.js';
-import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js';
-import type { EmergencySaveData } from '../../types/run/emergency.js';
-import type { Run, RunPersistenceConfig, StepResult, StopReason } from '../../types/run/index.js';
-import type { RunStore } from '../../types/run/store.js';
-import type { ProjectId, TopicId } from '../../types/session/ids.js';
-/**
- * The pair a rate lookup needs: which driver, running which model.
- *
- * `model` may be absent because a driver can be pointed at whatever the host
- * configured and some report nothing back. Absent resolves to no rate, which
- * is the honest answer, EXCEPT for a driver that bills nothing whatever it
- * runs — see `resolveModelPricing`.
- */
-export interface PricingSubject {
-    readonly providerId: string;
-    readonly model: string | undefined;
-}
-export declare class RunPersistence {
-    readonly budget?: TokenBudget;
-    private run;
-    private runStore;
-    private checkpointStore;
-    private pricing?;
-    /** See {@link recordTurnUsage}. */
-    private _lastPromptTokens?;
-    /** See {@link lastPromptMessageCount}. */
-    private _lastPromptMessageCount?;
-    private log;
-    private readonly _sessionId;
-    private readonly _topicId;
-    private readonly _tenantId;
-    private readonly _projectId;
-    constructor(config: RunPersistenceConfig);
-    get id(): RunId;
-    get sessionId(): SessionId;
-    get topicId(): TopicId;
-    get tenantId(): TenantId;
-    get projectId(): ProjectId;
-    get status(): import("../../types/common/index.js").RunExecutionStatus;
-    get stopReason(): StopReason | undefined;
-    get messages(): Message[];
-    get tokenUsage(): TokenUsage;
-    get costInfo(): CostInfo;
-    private syncBudget;
-    get currentIteration(): number;
-    getRun(): Readonly<Run>;
-    getSession(): Readonly<Run>;
-    getRunStore(): RunStore;
-    /**
-     * Checkpoint persistence for this run — the injected
-     * {@link CheckpointStore} when the host provided one, otherwise the
-     * disk default. Pair with {@link getRunScope} when constructing a
-     * `CheckpointManager`.
-     */
-    getCheckpointStore(): CheckpointStore;
-    /** Full five-layer scope key for this run's checkpoint operations. */
-    getRunScope(): CheckpointRunScope;
-    getRunDir(): string | null;
-    /**
-     * Highest sequence already in this run's durable event log.
-     *
-     * Seeded by {@link init} and advanced by {@link commitEventSeq}. Held here
-     * rather than on the event translator because the translator is built
-     * before `init` has run and would need a second, forgettable hop to learn
-     * the seed — where `init` is already mandatory, already awaited, and
-     * already the thing that binds the store.
-     */
-    private _lastEventSeq;
-    /** Highest sequence this run's log holds. Zero before anything is recorded. */
-    get lastEventSeq(): number;
-    /**
-     * Own counter for the audit trail's `seq` — a SEPARATE sequence space
-     * from {@link _lastEventSeq}. See `types/run/audit.ts`'s doc on
-     * `AuditEvent.seq`: the operational RunEvent transcript and the audit
-     * trail are two logs, and forcing them to share one counter just because
-     * both happen to be monotonic would make an unrelated burst on one trail
-     * move the other's cursor.
-     *
-     * Not chain-serialized against concurrent writers the way
-     * `EventTranslator.emitEvent` serializes `RunEvent.seq` (see
-     * `runtime/query/events.ts`'s `appendChain`) — every call site that
-     * exists today awaits each `recordAudit` before the next one starts for
-     * the same run. A future call site that fires audits concurrently would
-     * need the same serialization; add it there when that call site exists,
-     * not speculatively here.
-     */
-    private _lastAuditSeq;
-    init(): Promise<void>;
-    /**
-     * The number the NEXT durable event would take. Not yet taken — see
-     * {@link commitEventSeq}.
-     */
-    nextEventSeq(): number;
-    /**
-     * Take the candidate number, once its event is actually in the log.
-     *
-     * Split from {@link nextEventSeq} so a failed append consumes nothing: a
-     * `seq` is a claim that the event is recoverable, and advancing the counter
-     * before the write lands would leave a hole no event fills and hand a live
-     * consumer a cursor pointing at it.
-     */
-    commitEventSeq(seq: number): void;
-    markRunning(): void;
-    markCompleted(stopReason?: StopReason): void;
-    markFailed(error: string, providerError?: ProviderErrorInfo): void;
-    markCancelled(): void;
-    setStopReason(reason: StopReason): void;
-    setLastError(error: string): void;
-    incrementIteration(): number;
-    pushMessage(message: Message): void;
-    /** Replace the durable conversation projection without replacing the Run. */
-    replaceMessages(messages: readonly Message[]): void;
-    /**
-     * Who served the tokens being accumulated, so a rate can be found for them.
-     *
-     * Both fields are required. The previous signature took usage alone and
-     * priced it from one table the run was constructed with, which is why the
-     * only way to get a non-zero cost was for a host to pass that table — and
-     * no shipped surface did. Naming the subject at every call site is what
-     * lets the catalogue answer, and it makes a site that cannot say who served
-     * a compile error rather than a silent misattribution.
-     */
-    private resolvePricing;
-    accumulateUsage(usage: TokenUsage, servedBy: PricingSubject): void;
-    /**
-     * Accumulate usage from a MAIN-LOOP turn, and remember its prompt size.
-     *
-     * `tokenUsage.promptTokens` is cumulative across turns, so it says
-     * nothing about how full the context currently is. The last turn's
-     * prompt count does: it is the provider's own measurement of the
-     * context it just received. Compaction needs that number and nothing
-     * else gives it — a char/4 heuristic is the alternative.
-     *
-     * Side-channel calls (advisory, the compaction verifier, routing) use
-     * plain {@link accumulateUsage} instead: their prompts are not the
-     * run's context, and letting them write here would corrupt the signal.
-     */
-    recordTurnUsage(usage: TokenUsage, servedBy: PricingSubject): void;
-    /**
-     * Forget the last prompt measurement. Called after compaction: the
-     * reading described the context that was just replaced, so leaving it
-     * in place would re-trigger compaction against a window that no longer
-     * exists.
-     */
-    /**
-     * Attach the loop's per-iteration record to the run so a host that
-     * persists the returned `Run` keeps per-step attribution instead of
-     * having to reconstruct it from raw events.
-     */
-    /** Record the validated structured output on the run. */
-    /**
-     * Override the assembled result.
-     *
-     * Used by the output-guardrail rewrite path: the run produced text, a
-     * policy corrected it, and the corrected text is what `run_completed`
-     * and `Run.result` must carry.
-     */
-    /**
-     * Override the run's final text.
-     *
-     * The override is sticky: `resolveResult` re-derives the result from the
-     * message tail, and it runs again when the run settles, so without this
-     * flag a guardrail's redaction was silently re-expanded back to the raw
-     * model output at `markCompleted`. The previous code only survived that
-     * by settling the run EARLY — which is what made configuring a guardrail
-     * rewrite a cancelled run's status.
-     */
-    setResult(result: string): void;
-    /**
-     * Record the schema-validated answer, and make `result` agree with it.
-     *
-     * `result` used to be left alone here, and the consequence was not "empty"
-     * but "wrong": `resolveResult` walks back from the message tail and stops at
-     * the first non-assistant message, so a structured run — whose last
-     * assistant turn is a tool call, not prose — kept whatever text an EARLIER
-     * turn happened to produce. A host reading `run.result` got a sentence from
-     * the middle of the run presented as its answer.
-     *
-     * Three options, and the other two are worse:
-     *
-     *  - leave it: a stale value read as a fact, which is the defect;
-     *  - clear it: a run that plainly answered reports no answer, so a host
-     *    testing `if (run.result)` concludes nothing was produced;
-     *  - serialize the structured value into it, which is what this does.
-     *
-     * The serialization is not an invention. Every text-shaped consumer — the
-     * transcript, `Run.result`, both delegation tools handing a child's answer
-     * back to a parent model — needs the answer as a string, and each of them
-     * would otherwise serialize it again, differently. One serialization, at the
-     * moment the value is known.
-     *
-     * Sticky, via `setResult`: `resolveResult` runs again when the run settles,
-     * and without the override flag it would walk the tail and put the stale
-     * prose back.
-     */
-    /** Invalidate a structured value without replacing the host's textual result. */
-    clearStructuredOutput(): void;
-    setStructuredOutput(value: unknown): void;
-    /**
-     * Name the delegated work this run ended without waiting for.
-     *
-     * See {@link Run.abandonedTaskIds}. Recording rather than cancelling is
-     * the point: the kernel owes the caller the truth about what it walked
-     * away from, and nothing more.
-     */
-    setAbandonedTaskIds(taskIds: readonly string[]): void;
-    /**
-     * Name the awaited background jobs this run ended without waiting for.
-     *
-     * See {@link Run.abandonedJobIds}. The same rule as the task list above:
-     * recording, never stopping — what happens to a job is decided by whoever
-     * owns it, not by the run that gave up waiting.
-     */
-    setAbandonedJobIds(jobIds: readonly string[]): void;
-    setSteps(steps: readonly StepResult[]): void;
-    /**
-     * Record that a provider chain advanced, so the run record stops naming a
-     * member that did not serve.
-     *
-     * Last writer wins on purpose: a chain of four can advance three times in
-     * one run, and `metadata.servingProvider` answers "who was serving when
-     * this ended", not "who was ever asked". The full sequence is in the
-     * transcript's `provider_fallback` events and, per turn, in
-     * `steps[].servedBy`.
-     */
-    setServingProvider(providerId: string): void;
-    /**
-     * Who is serving right now, for a side-channel call that has no provenance
-     * of its own.
-     *
-     * The main loop does not use this — it reads `servedBy` off the turn, which
-     * is exact. Compaction and the closing summary go through the same wrapped
-     * provider without recording who answered, and this is the best available
-     * answer for them: the fallback decorator reports the head member's id
-     * whoever is actually serving, so asking the provider would hand back the
-     * declaration rather than the fact.
-     */
-    get servingProviderId(): string;
-    clearLastPromptTokens(): void;
-    /**
-     * Provider-reported size of the most recent main-loop prompt, or
-     * `undefined` before the first turn completes.
-     */
-    get lastPromptTokens(): number | undefined;
-    /**
-     * How many messages {@link lastPromptTokens} covers. Anything at or
-     * after this index was appended once the measurement was already taken
-     * and has to be accounted for separately.
-     */
-    get lastPromptMessageCount(): number | undefined;
-    /**
-     * Seed the spend counters from a checkpoint so a resumed run continues
-     * its budget instead of starting a fresh one.
-     *
-     * Without this, a run checkpointed at $4.80 of a $5 cap came back with a
-     * brand-new $5: a task that parked five times spent 5x its cap while
-     * every invocation truthfully reported itself in budget. The checkpoint
-     * already persisted all three values — they were written and discarded
-     * on the way back in.
-     *
-     * Restore, not accumulate: the caller holds a checkpoint's absolute
-     * totals, and adding them to a freshly-zeroed run would be the same
-     * arithmetic only by accident.
-     */
-    restoreUsage(tokenUsage: TokenUsage, costInfo: CostInfo, currentIteration: number): void;
-    /**
-     * Assemble the final assistant output WITHOUT settling the run.
-     *
-     * An output guardrail has to read what the run produced before it can
-     * judge it, and the only way to materialize that used to be
-     * `markCompleted()` — which force-marked a cancelled or paused run as
-     * `completed` merely because a guardrail was configured. Reading and
-     * settling are different operations; this is the read.
-     */
-    materializeResult(): string;
-    /** Set once a caller has explicitly supplied the final text. */
-    private resultOverridden;
-    private resolveResult;
-    toEmergencySnapshot(signal: string): EmergencySaveData;
-    /**
-     * Append one entry to this run's audit trail, and — only once that write
-     * has actually landed — emit the bridge pointer to the operational log.
-     * See ses_020's logging design §5.
-     *
-     * **Durability is unconditional and the failure mode is asymmetric with
-     * logging on purpose.** `RunStore.appendAuditEvent` is OPTIONAL on the
-     * contract (a host's custom store may not implement it, same as
-     * `addToIndex`), but silently running without an audit trail is exactly
-     * the degradation `refuse-do-not-degrade` forbids — so a bound store that
-     * lacks it is a THROWN error here, not a skipped write. Because this is
-     * called from every run's terminal path (see `runtime/query/result.ts`),
-     * a store lacking it will throw on the FIRST run against it — this is a
-     * major-version compatibility break for any host with a custom RunStore,
-     * documented as such in this release's changeset. When the store DOES
-     * implement it, a rejection from `appendAuditEvent` is NOT caught: it
-     * propagates to the caller, because an audit write failing must fail the
-     * operation it was recording — unlike `createLogger`'s `dispatch`, which
-     * swallows a throwing sink and counts it. See
-     * `manager/run/__tests__/audit-durability.test.ts`, which pins both
-     * halves of that asymmetry against ONE call, including the bridge log
-     * record below going through a throwing sink.
-     */
-    recordAudit(input: AuditEventInput): Promise<AuditEvent>;
-    persist(): Promise<void>;
-}
-//# sourceMappingURL=persistence.d.ts.map

package/dist/manager/run/persistence.d.ts.map

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