@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/approvals/held-run-release-wiring.d.ts

@@ -1,21 +1,16 @@
 /**
- * The release wiring the local (`kici-admin`) held-run decision surface runs on.
+ * The release wiring of the local (`kici-admin`) held-run decision surface,
+ * composed by `createApp` for every mode. A factory rather than an inline
+ * literal so a test can assert its fields: the defect it guards is a MISSING
+ * field — a release that flips the `held_runs` row without dispatching looks
+ * like it works and does nothing.
  *
- * `createApp` composes this for every mode. It lives here rather than inline in
- * that composition root because the defect it guards against is a MISSING
- * field, not a wrong algorithm: a release path that flips the `held_runs` row
- * without dispatching looks like it works and does nothing. A factory can be
- * constructed by a test and its fields asserted; an object literal buried in
- * `createApp` cannot.
+ * `undefined` without a job-release callback, so no decision route is mounted
+ * rather than one whose approves are silent no-ops.
  *
- * It returns `undefined` when there is no job-release callback, so an app
- * assembled without one mounts no decision route at all rather than one whose
- * approves are silent no-ops.
- *
- * Every callback reads the LIVE processing-deps bag at call time rather than
- * capturing one: the provider registry is swapped whenever sources reload, and
- * a captured bag would resolve a check poster from a registry that no longer
- * serves the routing key.
+ * Callbacks read the LIVE processing-deps bag at call time: sources reloading
+ * swap the provider registry, and a captured bag would resolve a check poster
+ * from a registry that no longer serves the routing key.
  */
 import type { ReleaseSignal } from '../contexts/held-runs.js';
 import type { ProcessingDeps } from '../pipeline/processor.js';
@@ -33,12 +28,10 @@ export interface HeldRunReleaseInputs {
     buildProcessingDeps: () => ProcessingDeps;
 }
 /**
- * The reason a workflow-scoped hold rejected through this surface records on the
- * run it cancels, when the operator supplied none.
- *
- * Scope-neutral on purpose: the install gate, the org trust policy's PR-wide
- * hold and an SDK workflow-level `requireApproval` all arrive here, so a
- * reason naming one of them would mislabel the other two.
+ * The reason recorded on the run when a workflow-scoped hold is rejected here
+ * with none supplied. Scope-neutral on purpose: the install gate, the org trust
+ * policy's PR-wide hold and an SDK workflow-level `requireApproval` all arrive
+ * here, so naming one would mislabel the others.
  */
 export declare const DEFAULT_LOCAL_REJECT_REASON = "Workflow hold rejected by the orchestrator operator";
 export declare function buildHeldRunRelease(inputs: HeldRunReleaseInputs): HeldRunReleaseWiring | undefined;

package/dist/approvals/independent-wiring.d.ts

@@ -2,25 +2,19 @@
  * The approval subsystem an INDEPENDENT orchestrator runs on.
  *
  * `server.ts` composes this inline for the three Platform-attached modes. An
- * independent orchestrator has no Platform and therefore none of that hook, so
- * every gate that raises a hold was inert there: a fork PR the org policy said
- * to HOLD was dropped instead of held, an SDK `requireApproval` job ran
- * UNGATED (the dispatch site logged an error and dispatched anyway), and the
- * stale detector had no store through which to expire an overdue hold,
- * terminalize its `KiCI Security` check, or drop the pending dispatch context
- * it would have replayed.
+ * independent orchestrator has no Platform hook, so without this every hold
+ * gate is inert: a fork PR the policy says to HOLD is dropped, an SDK
+ * `requireApproval` job runs UNGATED (the dispatch site logs an error and
+ * dispatches anyway), and the stale detector has no store to expire an overdue
+ * hold, terminalize its `KiCI Security` check, or drop its pending context.
  *
- * It lives here rather than inside `standalone.ts` because that module is an
- * entry point: it runs `guardStartup` at import time, so nothing can construct
- * its wiring in a test. A factory can be constructed, and the fields it
- * produces can be asserted — which is the whole point, since every defect this
- * closes was a missing field rather than a wrong algorithm.
+ * Not in `standalone.ts`: that entry point runs `guardStartup` at import time,
+ * so no test can construct its wiring. A factory's fields can be asserted —
+ * the point, since each defect this closes is a missing field.
  *
- * What it deliberately does NOT produce is a `stepApprovalBridge`. A
- * step-scoped hold is opened by the agent WS `onStepApproval` seam and answered
- * by the dashboard applier, which is Platform-relayed and has no
- * independent-mode equivalent — so wiring the bridge would let an agent open a
- * hold nothing could resolve short of expiry.
+ * Deliberately NO `stepApprovalBridge`: a step hold is answered by the
+ * Platform-relayed dashboard applier, which has no independent-mode
+ * equivalent, so an agent could open a hold nothing resolves short of expiry.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -38,9 +32,8 @@ export interface IndependentApprovalSubsystems {
     coordinator?: RunCoordinator | undefined;
     invokeGateDeps?: InvokeGateDeps | undefined;
     /**
-     * The live direct-ingress deps bag. Read lazily inside the release callbacks:
-     * it is populated by `createApp`, which runs after the mode hook, and reading
-     * it at wiring time throws.
+     * The live direct-ingress deps bag. Read lazily: `createApp` populates it
+     * after the mode hook, so reading it at wiring time throws.
      */
     buildProcessingDeps: () => ProcessingDeps;
 }

package/dist/approvals/resume-router.d.ts

@@ -1,5 +1,5 @@
 import type { ReleaseSignal } from '../contexts/held-runs.js';
-/** The three resume paths a released hold can take. */
+/** The resume paths a released hold can take. */
 export interface ResumeHandlers {
     onStepRelease?: (signal: ReleaseSignal) => Promise<void>;
     onWorkflowRelease?: (signal: ReleaseSignal) => Promise<void>;

package/dist/approvals/step-approval-bridge.d.ts

@@ -27,48 +27,38 @@ export interface StepApprovalRequest {
 export interface StepApprovalBridgeDeps {
     store: HeldRunStore;
     /**
-     * Resolve the orchestrator's tenant org id (same value the dashboard handler
-     * uses to read held_runs). A function because the org is resolved post-auth
-     * for sourceless orchestrators.
+     * The tenant org id the dashboard handler also reads held_runs with. A
+     * function because a sourceless orchestrator resolves its org post-auth.
      */
     resolveOrgId: () => string;
     /** Resolve the authoritative approval expiry (seconds) for an org. */
     resolveExpirySeconds: (orgId: string) => Promise<number>;
-    /**
-     * Access-log writer for the orchestrator audit stream. Optional -- if not
-     * set, the step-hold creation audit row (`held_run.request`) is skipped.
-     */
+    /** When unset, the `held_run.request` audit row is skipped. */
     accessLogWriter?: AccessLogWriter;
-    /** Routing key recorded on the audit row. Optional. */
+    /** Routing key recorded on the audit row. */
     routingKey?: string | null;
 }
 /**
- * Owns the step-scoped held_runs rows and the map from holdId → the waiting
- * agent's resolver. The only place that opens a step hold and the only place
- * that settles a step-scoped wait.
+ * Owns step-scoped held_runs rows and the holdId → waiting-agent resolver map:
+ * the only place that opens a step hold or settles a step-scoped wait.
  */
 export declare class StepApprovalBridge {
     private readonly deps;
     private readonly pending;
     constructor(deps: StepApprovalBridgeDeps);
-    /**
-     * Create a step-scoped hold and return a promise that settles when the hold
-     * is approved / rejected / expired (via {@link resolve}).
-     */
+    /** Create a step-scoped hold; the promise settles via {@link resolve}. */
     request(req: StepApprovalRequest): Promise<{
         outcome: StepApprovalOutcome;
         reason?: string;
     }>;
     /**
-     * Settle a step-scoped wait. Called by the approve/reject applier
-     * (`onStepRelease`) and by the stale detector (`expired`). A no-op when no
-     * agent is waiting on the hold (e.g. the agent already disconnected).
+     * Called by the applier (`onStepRelease`) and the stale detector (`expired`).
+     * A no-op when no agent waits on the hold (e.g. it already disconnected).
      */
     resolve(holdId: string, outcome: StepApprovalOutcome, reason?: string): boolean;
     /**
-     * Reject every pending wait for a disconnected agent. The held_runs rows are
-     * left as-is (the stale detector will expire them) — only the in-memory
-     * resolver is dropped so the handler's relayed `ws.send` is skipped.
+     * Reject a disconnected agent's pending waits so the handler skips `ws.send`.
+     * The held_runs rows stay for the stale detector to expire.
      */
     failAgent(agentId: string): void;
     /** Number of in-flight step-approval waits (test/diagnostics). */

package/dist/approvals/triggerer-subject.d.ts

@@ -19,19 +19,17 @@ export declare function adminActorSub(tokenUserId: string): string;
  * | anything else | unchanged | no other actor type reaches these surfaces |
  *
  * The agent suffix is stripped first. `stringifyActor` renders a `user` or
- * `api_key` who acted through an agent as `user:<sub> via agent:<label>`, and a
- * reader splitting on the first colon gets `<sub> via agent:<label>` — which
- * matches no live subject, so the gate was inert for every agent-mediated
- * trigger. That is the `user` case, i.e. the common one.
+ * `api_key` who acted through an agent as `user:<sub> via agent:<label>`, and
+ * splitting on the first colon alone gives `<sub> via agent:<label>`, which
+ * matches no live subject and leaves the gate inert for every agent-mediated
+ * trigger — the common `user` case.
  *
  * **Residual: `api_key`.** A key's persisted identifier is its `keyId`, while
  * both surfaces render a live `api_key` actor as its owner's Keycloak subject
- * (`ownerSub`). Those are different identifiers for the same principal and no
- * string transform bridges them — closing it needs a keyId → ownerSub lookup,
- * which is a store this pure function does not have. So an owner approving a
- * hold on a run their own key triggered is still admitted. Recorded rather than
- * papered over: returning the bare keyId is at least honest about what was
- * stored.
+ * (`ownerSub`). No string transform bridges them; closing it needs a keyId →
+ * ownerSub lookup, a store this pure function lacks. So an owner approving a
+ * hold on a run their own key triggered is still admitted. Returning the bare
+ * keyId is at least honest about what was stored.
  */
 export declare function triggererSubjectFor(triggeredBy: string | null | undefined): string | undefined;
 //# sourceMappingURL=triggerer-subject.d.ts.map

package/dist/artifacts/artifact-store.d.ts

@@ -3,10 +3,9 @@ import type { ArtifactRejectReason } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 import type { CacheStorage } from '../storage/types.js';
 /**
- * The presigned PUT never landed an object, so there is nothing to record.
- * Distinct from a transient storage/DB error: a caller retrying the commit
- * would keep finding the object absent, so this failure is terminal and is
- * reported straight back to the agent (which fails the workflow step).
+ * The presigned PUT never landed an object. Terminal, unlike a transient
+ * storage/DB error (a retry would keep finding it absent), so it goes straight
+ * back to the agent, which fails the workflow step.
  */
 export declare class ArtifactObjectMissingError extends Error {
     readonly storageKey: string;
@@ -20,16 +19,13 @@ export declare class ArtifactInvalidNameError extends Error {
     constructor(detail: string);
 }
 /**
- * Map a `completeUpload` failure onto a message safe to send to the agent — which
- * runs untrusted workflow code, so the reason reaches the workflow author and its
- * step logs.
+ * Map a `completeUpload` failure onto a message safe for the agent, which runs
+ * untrusted workflow code (the reason reaches the author's step logs).
  *
- * An invalid-name error already carries a safe message: its constructor formats
- * the schema's own fixed detail, so it passes through unchanged. An object-missing
- * error is a genuinely actionable terminal case and keeps its own category, but
- * the storage key its message embeds does not travel. Anything else is an internal
- * failure the author cannot act on, so it collapses to one literal; the raw
- * exception stays in the orchestrator's own log line.
+ * An invalid-name message is already safe (the schema's fixed detail) and
+ * passes through. Object-missing keeps its own category, but not the storage
+ * key its message embeds. Anything else collapses to one literal; the raw
+ * exception stays in the orchestrator's own log.
  */
 export declare function classifyArtifactCommitFailure(err: unknown): string;
 /** Cluster-wide default per-org artifact byte quota: 20 GiB. */
@@ -41,36 +37,24 @@ export declare const DEFAULT_ARTIFACT_MAX_BYTES: number;
 /** Cluster-wide default per-run artifact count cap. */
 export declare const DEFAULT_ARTIFACT_MAX_PER_RUN = 50;
 /**
- * Storage key for a run's named artifact.
+ * Storage key for a run's named artifact. Injective over names, so a second
+ * upload can never silently overwrite the first while both rows keep their own
+ * hash.
  *
- * Injective over names: distinct names always produce distinct keys, so a
- * second upload can never silently overwrite the first while both rows keep
- * their own hash.
+ * The trailing discriminator, a hash of the EXACT name, keeps keys apart on a
+ * CASE-INSENSITIVE namespace (the filesystem backend on macOS or Windows),
+ * where `bundle` and `Bundle` would otherwise resolve to one file. Under case
+ * folding it carries the whole separation, hence its width (see
+ * `KEY_DISCRIMINATOR_LENGTH`). The readable stem lets an operator browsing the
+ * bucket tell which artifact an object is. Hashing the sanitized name instead
+ * would fold `a/b` and `a_b` back together.
  *
- * The trailing discriminator is a hash of the exact name, and it is what keeps
- * the keys apart on a CASE-INSENSITIVE object namespace — the filesystem
- * backend on a macOS or Windows host. There `bundle` and `Bundle` would
- * otherwise be two keys resolving to one file; because their discriminators
- * differ, the keys differ by more than case and stay two objects. That is why
- * the discriminator is wide (see `KEY_DISCRIMINATOR_LENGTH`): under case
- * folding it carries the whole separation on its own. The readable stem is kept
- * so an operator browsing the bucket can still tell which artifact an object
- * is.
- *
- * Hashing the EXACT name rather than the sanitized one is deliberate:
- * sanitizing is many-to-one, so a discriminator over its output would fold
- * `a/b` and `a_b` back together.
- *
- * Changing this format does not strand existing artifacts — the key is
- * persisted in `artifacts.storage_key` and the download paths read that column
- * rather than re-deriving. Only the grant and commit paths derive, and both do
- * so at upload time.
+ * Changing this format does not strand existing artifacts: downloads read the
+ * persisted `artifacts.storage_key`; only the grant and commit paths derive,
+ * both at upload time.
  */
 export declare function artifactStorageKey(runId: string, name: string): string;
-/**
- * Per-org override of the artifact limits, read from `org_settings`. Each field
- * is optional; an undefined field falls back to the cluster-wide default.
- */
+/** Per-org `org_settings` overrides; an undefined field uses the cluster default. */
 export interface ArtifactOrgLimits {
     quotaBytes?: number;
     ttlMs?: number;
@@ -85,10 +69,7 @@ export interface ArtifactBeginUploadResult {
     uploadUrl?: string;
     storageKey?: string;
     reason?: ArtifactRejectReason;
-    /**
-     * Free-text rejection detail carried when no enforcement `reason` applies —
-     * today, a name that violates the artifact-name contract.
-     */
+    /** Free-text detail when no enforcement `reason` applies (a contract-violating name). */
     error?: string;
 }
 /** Outcome of a download lookup. */
@@ -105,11 +86,7 @@ export interface ArtifactListEntry {
     sizeBytes: number;
     sha256: string;
     createdAt: string;
-    /**
-     * Presigned GET for the backing object. Present on the run-detail listing
-     * (`listForRunWithUrls`); omitted when the object could not be resolved
-     * (expired / gone).
-     */
+    /** Presigned GET (`listForRunWithUrls`); omitted when the object is expired or gone. */
     downloadUrl?: string;
 }
 export declare class ArtifactStore {
@@ -127,34 +104,25 @@ export declare class ArtifactStore {
         quotaBytes?: number;
         /** Cluster-wide default TTL (env default). */
         ttlMs?: number;
-        /** Per-artifact size cap. */
         maxBytes?: number;
-        /** Per-run artifact count cap. */
         maxPerRun?: number;
-        /** Per-org override reader (org_settings). When unset, defaults apply. */
+        /** When unset, defaults apply. */
         orgLimitsReader?: ArtifactOrgLimitsReader;
     });
-    /**
-     * Resolve the effective quota, TTL, per-artifact size cap, and per-run count
-     * cap for an org. Each value is the per-org `org_settings` override when set,
-     * otherwise the cluster-wide default.
-     */
+    /** Effective limits for an org: the `org_settings` override, else the default. */
     private resolveLimits;
-    /** ISO cutoff for TTL filtering: rows created before this are expired. */
+    /** Cutoff time for TTL filtering: rows created before this are expired. */
     private cutoff;
     /**
-     * Grant or refuse a presigned PUT for a named artifact. Order: name contract →
-     * resolve limits → size cap → duplicate name → per-run count cap → org quota.
-     * The size cap and per-run count cap are the resolved per-org override when
-     * set, otherwise the cluster-wide default. No presigned URL is minted for a
-     * request that would violate any gate.
+     * Grant or refuse a presigned PUT. Order: name contract → resolve limits →
+     * size cap → duplicate name → per-run count cap → org quota. No URL is minted
+     * for a request violating any gate.
      *
-     * The name is checked first, and here rather than only in the SDK, because the
-     * agent runs untrusted customer workflow code: a name that bypassed the SDK
-     * check would be sanitized onto another name's storage key, letting a second
-     * upload overwrite the first object while both rows keep their own hash. A
-     * contract violation is not an enforcement rejection, so it carries a
-     * free-text `error` and no `reason`.
+     * The name is checked here, not only in the SDK, because the agent runs
+     * untrusted workflow code: a name bypassing the SDK check would be sanitized
+     * onto another name's key, letting a second upload overwrite the first object
+     * while both rows keep their own hash. A contract violation is not an
+     * enforcement rejection, so it carries a free-text `error` and no `reason`.
      */
     beginUpload(args: {
         customerId: string;
@@ -163,29 +131,23 @@ export declare class ArtifactStore {
         declaredSizeBytes: number;
     }): Promise<ArtifactBeginUploadResult>;
     /**
-     * Commit a completed upload: write the object metadata sidecar, then insert
-     * the DB row. The `UNIQUE (run_id, name)` constraint (via onConflict-do-nothing)
-     * is the immutability backstop for a racing duplicate that slipped past the
-     * pre-mint check.
+     * Commit a completed upload: write the metadata sidecar, then insert the row.
+     * `UNIQUE (run_id, name)` (onConflict-do-nothing) backstops a racing duplicate
+     * that slipped past the pre-mint check.
      *
-     * The agent asserts neither the key nor the size: the storage key is derived
-     * from the server-resolved `runId` + `name`, and the recorded size is the real
-     * byte size of the stored object read back from the storage backend. Agents
-     * run untrusted customer workflow code, so an echoed key could otherwise point
-     * a row at another tenant's object, and a declared size could under-account
-     * the per-org quota (a presigned PUT does not bind content length).
+     * The agent asserts neither key nor size: the key derives from the
+     * server-resolved `runId` + `name`, the size is read back from storage.
+     * Agents run untrusted code, so an echoed key could point a row at another
+     * tenant's object, and a declared size could under-account the org quota (a
+     * presigned PUT does not bind content length).
      *
-     * The name is re-validated here, not only at `beginUpload`: a commit is its
-     * own inbound message, so an agent can send one for a name it never got a
-     * grant for. Without the check, a non-conforming name would derive the
-     * storage key of a *different*, already-committed artifact and record a second
-     * row against that same object with its own hash.
+     * The name is re-validated: a commit is its own inbound message, possibly for
+     * a name never granted, and a non-conforming name would derive the key of a
+     * *different*, already-committed artifact and record a second row against it.
      *
-     * Throws when the commit cannot be recorded — `ArtifactInvalidNameError` for a
-     * name that violates the contract, `ArtifactObjectMissingError` when the
-     * presigned PUT never landed an object, or the underlying storage / DB error
-     * otherwise. The caller reports the failure back to the agent, which fails the
-     * workflow step rather than leaving a green run with no artifact.
+     * Throws `ArtifactInvalidNameError`, `ArtifactObjectMissingError`, or the
+     * underlying storage / DB error. The caller reports it to the agent, which
+     * fails the step rather than leaving a green run with no artifact.
      */
     completeUpload(args: {
         customerId: string;
@@ -210,13 +172,11 @@ export declare class ArtifactStore {
     /** Load a run's non-expired artifact rows, newest first, given the org TTL. */
     private loadRunRows;
     /**
-     * List a run's non-expired artifacts with a presigned GET per entry, newest
-     * first — the shape the dashboard run-detail panel renders. Resolves the org
-     * TTL once, then mints one presigned URL per row; a row whose backing object
-     * is gone lists its metadata with `downloadUrl` omitted rather than being
-     * dropped. Also reports the presigned-URL expiry (seconds) — the storage
-     * backend's `getUrl` signature TTL, NOT the artifact-retention `ttlMs` — so
-     * the dashboard can refresh a rendered `downloadUrl` before its signature
+     * A run's non-expired artifacts with a presigned GET each, newest first, for
+     * the dashboard run-detail panel. A row whose object is gone keeps its
+     * metadata with `downloadUrl` omitted rather than being dropped. Also reports
+     * the presigned-URL expiry in seconds — the backend's `getUrl` signature TTL,
+     * NOT the retention `ttlMs` — so the dashboard can refresh a URL before it
      * expires.
      */
     listForRunWithUrls(customerId: string, runId: string): Promise<{

package/dist/artifacts/failure-messages.d.ts

@@ -1,19 +1,16 @@
 /**
  * Safe, fixed messages the orchestrator sends to the agent (and through it to
- * the workflow author) when a user-artifact request is refused for something
- * other than an enforcement gate or a genuine lookup miss — an internal failure,
- * or a request that violates the artifact-name contract.
+ * the workflow author) when a user-artifact request is refused for an internal
+ * failure or an artifact-name contract violation, rather than an enforcement
+ * gate or a genuine lookup miss.
  *
- * These are presentation strings, not a wire vocabulary: the protocol carries
- * them in the free-text `error` field of `artifacts.upload.response` /
- * `artifacts.download.response` and in the free-text `reason` field of
- * `artifacts.upload.complete.ack`, so an orchestrator is free to reword them
- * without any agent-side change. They live here — rather than inline at each
- * send site — so the handler and its tests share one definition.
+ * Presentation strings, not a wire vocabulary: they ride the free-text `error`
+ * of `artifacts.upload.response` / `artifacts.download.response` and `reason`
+ * of `artifacts.upload.complete.ack`, so they can be reworded with no agent
+ * change. Defined once so the handler and its tests share them.
  *
- * Raw exception text is never one of these. Exceptions stay in the
- * orchestrator's own logs; the author sees only "this is an orchestrator or
- * configuration problem", never a database endpoint or a stack frame.
+ * Raw exception text is never sent: it stays in the orchestrator's logs, and
+ * the author never sees a database endpoint or a stack frame.
  */
 export declare const ArtifactInternalFailure: Readonly<{
     /** Upload requested but the orchestrator has no artifact store configured. */
@@ -32,15 +29,13 @@ export declare const ArtifactInternalFailure: Readonly<{
     readonly commitObjectMissing: 'the uploaded artifact object was not found in storage — the upload may not have completed';
 }>;
 /**
- * The artifact-name rejection prefix and message builder are defined in
- * `@kici-dev/engine`, beside `ArtifactNameSchema` itself, so the orchestrator and
- * the agent sandbox render one wording. Such a rejection is neither an
+ * Defined in `@kici-dev/engine` beside `ArtifactNameSchema`, so the orchestrator
+ * and the agent sandbox render one wording. A name rejection is neither an
  * enforcement gate (nothing about the org's usage refuses it) nor an internal
- * failure — the sandbox validates the same contract at the call site, so a name
- * only reaches this path from an agent that bypassed or predates that check.
- *
- * Re-exported here because this module is where the orchestrator's artifact
- * failure messages live — callers keep their existing import path.
+ * failure. The sandbox validates the same contract at the call site, so an
+ * invalid name only reaches the orchestrator from an agent that bypassed or
+ * predates that check. Re-exported so callers import every artifact failure
+ * message from here.
  */
 export { ARTIFACT_INVALID_NAME_PREFIX, artifactInvalidNameError } from '@kici-dev/engine';
 //# sourceMappingURL=failure-messages.d.ts.map

package/dist/audit/access-log.d.ts

@@ -16,10 +16,8 @@ export interface AccessLogRecord {
     outcome: AccessLogOutcome;
     errorMessage?: string | null;
     /**
-     * Extra key/value pairs merged into `actor_meta` on insert. Lets
-     * callers attach action-specific context (e.g. which dashboard-write
-     * operation flipped) without overloading other columns. Values must
-     * be JSON-serialisable.
+     * Merged into `actor_meta` on insert, for action-specific context (e.g. which
+     * dashboard-write operation flipped). Values must be JSON-serialisable.
      */
     meta?: Record<string, unknown>;
 }
@@ -48,15 +46,13 @@ export interface AccessLogQueryResult {
     nextCursor: string | null;
 }
 /**
- * Best-effort writer for the orchestrator `access_log` table. Records one
- * row per read / orchestrator-admin mutation attributable to an
- * ActorPrincipal. Callers get their actor from the incoming Platform proxy
- * message (`msg.actor`) or from the admin HTTP auth chain.
+ * Best-effort writer for `access_log`: one row per read / orchestrator-admin
+ * mutation attributable to an ActorPrincipal (from the Platform proxy's
+ * `msg.actor` or the admin HTTP auth chain).
  *
- * Failure mode: insert errors are logged and swallowed — a broken
- * access_log table MUST NOT take down dashboard reads. Use `secret_audit_log`
- * for the always-consistent secret mutation path; `access_log` is the
- * read + broad-surface audit stream.
+ * Insert errors are logged and swallowed — a broken access_log MUST NOT take
+ * down dashboard reads. `secret_audit_log` is the always-consistent secret
+ * mutation path; `access_log` is the read + broad-surface audit stream.
  */
 export declare class AccessLogWriter {
     private readonly db;
@@ -64,53 +60,39 @@ export declare class AccessLogWriter {
     private readonly rateLimiter;
     constructor(db: Kysely<Database>, coldStore?: ColdStore, rateLimiter?: AccessLogRateLimiter);
     /**
-     * Late-binding setter for the cold-store handle. orchestrator-core
-     * builds AccessLogWriter before the cold-store singleton, then
-     * attaches it via this setter (mirrors AuditLogger.setColdStore).
+     * Late binding: orchestrator-core builds this before the cold-store
+     * singleton (mirrors AuditLogger.setColdStore).
      */
     setColdStore(coldStore: ColdStore | null): void;
     record(entry: AccessLogRecord): Promise<void>;
     /**
-     * Transactional variant: writes the row through the caller's executor so it
-     * commits or rolls back with the mutation it audits.
+     * Writes through the caller's executor so the row commits or rolls back with
+     * the mutation it audits. Unlike `record`, failures PROPAGATE: a caller that
+     * opts into a transaction asserts the mutation must not land unaudited.
      *
-     * Unlike `record`, failures PROPAGATE. The best-effort swallow exists so a
-     * broken `access_log` cannot take down dashboard reads; a caller that opted
-     * into a transaction is asserting the opposite — the mutation must not land
-     * unaudited — so the error has to reach the transaction and abort it.
-     *
-     * The per-action `POLICY_BY_ACTION` gate still applies, so a `sample` /
-     * `rate_limit` action would be dropped here silently and the caller's
-     * mutation would commit unaudited after all. Callers must therefore use an
-     * action whose policy is `always` — which is why `trust_policy.updated` is
-     * one.
+     * The `POLICY_BY_ACTION` gate still applies, so a `sample` / `rate_limit`
+     * action would be dropped silently and the mutation would commit unaudited.
+     * Callers must use an `always` action — why `trust_policy.updated` is one.
      */
     recordInTransaction(executor: Kysely<Database> | Transaction<Database>, entry: AccessLogRecord): Promise<void>;
     private insert;
     /**
-     * Delegates to `loadAccessLogRange` so cold-store rows are
-     * merged transparently when pagination crosses the warm cutoff. The
-     * caller-visible `{items, nextCursor}` shape is preserved. NO
-     * --include-archived flag — access_log is "paginated/transparent".
+     * Cold-store rows merge transparently when pagination crosses the warm
+     * cutoff. NO --include-archived flag — access_log is "paginated/transparent".
      */
     query(filter: AccessLogQueryFilter): Promise<AccessLogQueryResult>;
     /**
-     * Detail lookup by row id. Hot first; on miss falls back to a single
-     * cold-store tenant scan filtering by `id`. Mirrors the
-     * `loadEventLogByDeliveryId` pattern in `load-event-log-range.ts` —
-     * cold-store is partitioned by `(tenant_id, day)` with no cross-tenant
-     * `id` index, so the caller MUST scope the cold scan to one tenant.
+     * Hot first, then one cold-store tenant scan by `id` (like
+     * `loadEventLogByDeliveryId` in `load-event-log-range.ts`): cold-store is
+     * partitioned by `(tenant_id, day)` with no cross-tenant `id` index, so the
+     * scan MUST be scoped to one tenant.
      *
-     * `opts.orgId` supplies the tenant scope. When omitted, only the
-     * synthetic `__orchestrator__` tenant is scanned (matches the
-     * NULL-org_id rows the orchestrator itself emits via
-     * `cold-store-archive` / `cold-store-purge`). The CLI exposes this as
-     * `kici-admin access-log show <id> --org <orgId>`.
+     * `opts.orgId` is that scope; omitted ⇒ only the synthetic `__orchestrator__`
+     * tenant (the NULL-org_id rows `cold-store-archive` / `cold-store-purge`
+     * emit). CLI: `kici-admin access-log show <id> --org <orgId>`.
      *
-     * Best-effort contract: a cold-store error logs a warn line and
-     * returns null, matching `loadAccessLogRange` and
-     * `loadEventLogByDeliveryId`. A transient S3 outage MUST NOT
-     * manufacture a misleading 404-vs-500 distinction at the HTTP layer.
+     * Best-effort, like `loadAccessLogRange`: a cold-store error warns and returns
+     * null, so a transient S3 outage never fakes a 404-vs-500 distinction.
      */
     getById(id: string, opts?: {
         orgId?: string;