@hasna/loops 0.4.14 → 0.4.22

package/dist/types.d.ts

@@ -212,6 +212,8 @@ export interface WorkflowWorkItem {
     subjectRef: string;
     projectKey?: string;
     projectGroup?: string;
+    /** Machine that reserved/admitted this route work item, when known. */
+    machineId?: string;
     /**
      * The drain/route identity (loop name) that admitted this item. Used to scope
      * the `--max-active` global admission count to a single route instead of the
@@ -239,6 +241,7 @@ export interface UpsertWorkflowWorkItemInput {
     subjectRef: string;
     projectKey?: string;
     projectGroup?: string;
+    machineId?: string;
     routeScope?: string;
     priority?: number;
     status?: Extract<WorkflowWorkItemStatus, "queued" | "deferred">;
@@ -394,6 +397,52 @@ export interface LoopRun {
     createdAt: string;
     updatedAt: string;
 }
+export type RunReceiptMachine = string | Record<string, unknown>;
+export interface RunReceiptSummary {
+    text?: string;
+    stdout_bytes: number;
+    stderr_bytes: number;
+    stdout_excerpt?: string;
+    stderr_excerpt?: string;
+    error?: string;
+    duration_ms?: number;
+}
+export interface RunReceipt {
+    loop_id: string;
+    run_id: string;
+    machine: RunReceiptMachine;
+    repo: string;
+    task_ids: string[];
+    knowledge_ids: string[];
+    digest_id: string;
+    started_at: string | null;
+    finished_at: string | null;
+    status: string;
+    exit_code: number | null;
+    summary: RunReceiptSummary;
+    evidence_paths: string[];
+    created_at: string;
+    updated_at: string;
+}
+export interface WriteRunReceiptInput {
+    loop_id?: string;
+    run_id: string;
+    machine?: RunReceiptMachine;
+    repo?: string;
+    task_ids?: string[];
+    knowledge_ids?: string[];
+    digest_id?: string;
+    started_at?: string | null;
+    finished_at?: string | null;
+    status?: string;
+    exit_code?: number | null;
+    summary?: string | Partial<RunReceiptSummary> | null;
+    evidence_paths?: string[];
+    stdout?: string;
+    stderr?: string;
+    error?: string;
+    duration_ms?: number;
+}
 export interface CreateLoopInput {
     name: string;
     description?: string;

package/docs/AUTOMATION_RUNTIME_DESIGN.md

@@ -7,6 +7,9 @@ materialization, queue state, approvals, DLQ/replay, idempotency, and audit
 evidence. OpenLoops owns workflow invocation, admission, execution, run
 manifests, and provider routing once work is explicitly handed off.
 
+For operator-facing ownership tables, handoff path examples, and anti-patterns,
+see [Runtime Boundary](./RUNTIME_BOUNDARY.md).
+
 ## Planned Workflow Upsert SDK
 
 External compilers should not write OpenLoops SQLite rows directly. The stable
@@ -52,7 +55,8 @@ type WorkflowUpsertResult = {
     manifestPath?: string;
   };
   action: "created" | "updated" | "reused" | "rejected";
-  preflight?: { ok: boolean; checks: unknown[]; error?: string };
+  preflight?: AutomationPreflightResult;
+  evidence?: AutomationEvidenceSummary;
 };
 ```
 
@@ -73,6 +77,222 @@ Required semantics:
   for the caller to inspect, cancel, replay, or resolve the run without querying
   SQLite directly.
 
+## Planned Actions Target Binding
+
+`@hasna/actions` now exposes typed action contracts: `ActionManifest`,
+`ActionInvocation`, `ActionRun`, `ActionRunStatus`, `ActionQueueStatus`,
+`ActionAuditEvent`, `EvidenceRef`, and `ActionDeadLetter`. A future OpenLoops
+action binding must reuse those contracts instead of adding an OpenLoops-owned
+action status, action queue, or idempotency dialect.
+
+The binding should be a workflow-admission descriptor, not a direct executor in
+the first implementation:
+
+```ts
+type ActionsRuntimeBinding = {
+  integration: "hasna-actions";
+  role: "workflow-runtime";
+  targetType: "action";
+  actionOwner: "@hasna/actions";
+  runtimeOwner: "@hasna/loops";
+  handoff: "workflow-upsert";
+  statusModel: "action-owned";
+};
+
+type ActionTargetBindingRequest = {
+  type: "action";
+  action: {
+    id: string;
+    version: string;
+    invocationId?: string;
+    runId?: string;
+    idempotencyKey?: string;
+    dedupeKey?: string;
+  };
+  subject?: WorkflowUpsertRequest["subject"];
+  workflow: WorkflowUpsertRequest["workflow"];
+  route?: WorkflowUpsertRequest["route"];
+  execution?: WorkflowUpsertRequest["execution"];
+  mode?: WorkflowUpsertRequest["mode"];
+  dispatch?: WorkflowUpsertRequest["dispatch"];
+};
+```
+
+The planned implementation path is:
+
+1. The action owner validates the manifest, input, actor, approvals, dry-run
+   support, idempotency requirement, guardrails, audit fields, evidence fields,
+   and rollback policy using `@hasna/actions`.
+2. The action owner passes only a normalized `ActionTargetBindingRequest` or
+   `WorkflowUpsertRequest` to OpenLoops. Large inputs, private prompts, secret
+   values, and mutable action state stay in the action store or a referenced
+   artifact.
+3. OpenLoops admits a one-shot workflow loop through the planned upsert
+   contract, records workflow/run/manifests refs, and reports those refs back to
+   the action owner.
+4. The action owner records `ActionAuditEvent` and `EvidenceRef` entries that
+   include the returned OpenLoops refs. OpenLoops may store source refs for
+   lookup, but `@hasna/actions` remains the source of truth for action runs and
+   queue state.
+
+### Request And Result Mapping
+
+`ActionManifest.id` and `ActionManifest.version` map to
+`WorkflowUpsertRequest.source.id` and the canonical workflow hash input:
+
+```ts
+const request: WorkflowUpsertRequest = {
+  idempotencyKey:
+    invocation.idempotencyKey ??
+    `actions:${manifest.id}:${manifest.version}:${invocation.id}`,
+  source: {
+    kind: "action",
+    id: manifest.id,
+    dedupeKey: invocation.idempotencyKey ?? invocation.id,
+  },
+  subject: subjectFromAction(manifest, invocation),
+  workflow: renderedWorkflow,
+  loop: { name: `action-${manifest.id}`, schedule: { type: "once", at } },
+  route,
+  execution,
+  mode,
+  dispatch,
+};
+```
+
+`specHash` must be computed from the canonical OpenLoops workflow request plus
+the stable action contract identity: action id, manifest version, idempotency
+key or invocation id, selected executor binding kind/ref, route policy, and
+execution policy. It must not include raw secret values, raw credentials, or
+unredacted prompt bodies. If `@hasna/actions` later publishes its own manifest
+hash, OpenLoops should include that hash instead of re-hashing action internals.
+
+`WorkflowUpsertResult` keeps its existing semantics:
+
+- `idempotencyKey` is the action-owned idempotency key selected above.
+- `specHash` identifies the exact OpenLoops workflow admission request and
+  action contract identity that produced it.
+- `refs.workflowId`, `refs.loopId`, `refs.invocationId`, `refs.workItemId`,
+  `refs.runId`, and `refs.manifestPath` are OpenLoops refs that the action
+  owner can store as `EvidenceRef` or audit event data.
+- `action="created" | "updated" | "reused" | "rejected"` describes OpenLoops
+  materialization only. It is not an action run status.
+- Action run fields such as `status`, `dedupedFromRunId`, `evidence`, `events`,
+  and `error` remain on `ActionRun`.
+
+### Status Translation
+
+OpenLoops should translate its workflow and work-item state into action-owned
+status updates without persisting a new action status enum.
+
+Recommended initial translation:
+
+- An accepted dry-run/preflight maps to an `ActionRun` that remains
+  `planned`, `previewed`, or `awaiting_approval` according to
+  `@hasna/actions`; OpenLoops only returns preflight details.
+- A scheduled workflow maps to action queue status `queued` or
+  `waiting_approval`, depending on action-owned approval gates.
+- A claimed/running workflow maps to action queue status `claimed` and action
+  run status `executing`.
+- A successful workflow maps to action queue status `succeeded` and action run
+  status `succeeded`.
+- A terminal workflow failure maps to action queue status `failed` or `dead`
+  and action run status `failed`; the action owner decides whether the
+  `ActionDeadLetter.replayable` flag is true.
+- Operator cancellation maps to action queue status `cancelled` and action run
+  status `cancelled`.
+
+These mappings are adapter behavior. OpenLoops should expose its own workflow
+statuses for OpenLoops APIs and should call or return enough refs for
+`@hasna/actions` to update `ActionRun`, `ActionQueueStatus`, audit events, and
+dead-letter records.
+
+### Failure And Replay
+
+Failure handling must flow through action-owned APIs:
+
+- Provider, worktree, account, policy, and command failures are classified by
+  OpenLoops and returned as redacted workflow error evidence.
+- The action owner turns those failures into `ActionError`,
+  `ActionDeadLetter`, `ActionAuditEvent`, and `EvidenceRef` records.
+- Replay starts from an action-owned replay decision and a new action-owned
+  idempotency key. OpenLoops then receives a new upsert request whose
+  `source.dedupeKey` and `idempotencyKey` are the replay keys.
+- OpenLoops DLQ commands may mirror or inspect linked workflow failures, but
+  they must not fabricate action queue entries or mark an action replayable on
+  their own.
+
+### Mode And Dispatch Examples
+
+Dry-run without OpenLoops mutation:
+
+```bash
+actions run deploy.manifest.json \
+  --input-file deploy-input.json \
+  --idempotency-key deploy:preview:42 \
+  --dry-run \
+  --json
+
+loops workflows upsert-one-shot deploy-workflow.json \
+  --idempotency-key deploy:preview:42 \
+  --source-kind action \
+  --source-id deploy.service \
+  --mode dry-run \
+  --dispatch none \
+  --json
+```
+
+Preflight before scheduling:
+
+```bash
+loops workflows upsert-one-shot deploy-workflow.json \
+  --idempotency-key deploy:release:42 \
+  --source-kind action \
+  --source-id deploy.service \
+  --mode preflight \
+  --dispatch schedule \
+  --json
+```
+
+Commit and run immediately after the action owner approves:
+
+```bash
+actions approve <action-run-id> --reason "preview accepted" --json
+
+loops workflows upsert-one-shot deploy-workflow.json \
+  --idempotency-key deploy:release:42 \
+  --source-kind action \
+  --source-id deploy.service \
+  --mode commit \
+  --dispatch run-now \
+  --json
+```
+
+Commit without dispatch, for another owner to trigger later:
+
+```bash
+loops workflows upsert-one-shot deploy-workflow.json \
+  --idempotency-key deploy:release:42 \
+  --source-kind action \
+  --source-id deploy.service \
+  --mode commit \
+  --dispatch none \
+  --json
+```
+
+### Non-Goals
+
+- Do not let `@hasna/actions` write OpenLoops SQLite/Postgres rows directly.
+- Do not duplicate the action queue in OpenLoops.
+- Do not materialize triggers in OpenLoops; action and automation owners decide
+  when a concrete invocation exists.
+- Do not store secret values, unredacted prompts, credentials, or private
+  action input payloads in workflow specs, prompts, manifests, task comments,
+  or run output.
+- Do not add `target.type = "action"` as an executable target until the action
+  package has a stable runtime handoff API that can complete, fail, audit, and
+  replay action runs by action-owned refs.
+
 ## CLI Surface
 
 The planned CLI should mirror the SDK:
@@ -96,6 +316,227 @@ loops workflows upsert-one-shot ./workflow.json \
 would fail. `--mode commit` must return the durable refs required for later
 inspection and replay.
 
+## Planned Automation Preflight API
+
+Automation-generated workflows need an aggregate preflight result that is richer
+than the current `PreflightResult` command/account tuple, but still compact
+enough to return from CLI, SDK, MCP, route drains, and run manifests. The API is
+a reporting contract first; implementation should reuse existing validators in
+`workflow-spec.ts`, provider capability metadata in `agent-adapter.ts`, account
+resolution in `accounts.ts`, machine/worktree checks in `executor.ts`, and
+redaction helpers in `redact.ts`.
+
+Proposed SDK shape:
+
+```ts
+type AutomationPreflightMode = "dry-run" | "preflight" | "commit";
+
+type AutomationPreflightDomain =
+  | "spec"
+  | "provider"
+  | "account"
+  | "command"
+  | "secret"
+  | "connector"
+  | "permissions"
+  | "sandbox"
+  | "worktree"
+  | "machine"
+  | "allowlist"
+  | "redaction"
+  | "evidence";
+
+type AutomationPreflightStatus = "pass" | "warn" | "fail" | "skipped";
+type AutomationPreflightSeverity = "info" | "warning" | "error" | "fatal";
+
+type AutomationPreflightClassification =
+  | "validation"
+  | "provider"
+  | "account"
+  | "auth"
+  | "command"
+  | "secret"
+  | "connector"
+  | "policy"
+  | "permission"
+  | "sandbox"
+  | "worktree"
+  | "machine"
+  | "redaction"
+  | "unknown";
+
+type AutomationPreflightCheck = {
+  id: string;
+  domain: AutomationPreflightDomain;
+  status: AutomationPreflightStatus;
+  severity: AutomationPreflightSeverity;
+  classification: AutomationPreflightClassification;
+  stepId?: string;
+  targetType?: "command" | "agent" | "workflow";
+  provider?: AgentProvider;
+  account?: { profile: string; tool?: string };
+  command?: string;
+  subject?: { kind: string; ref?: string };
+  summary: string;
+  remediation?: string;
+  evidenceRefs?: Array<{ kind: "manifest" | "run" | "workflow" | "loop" | "workItem" | "external"; ref: string }>;
+  redacted: true;
+};
+
+type AutomationPreflightResult = {
+  ok: boolean;
+  mode: AutomationPreflightMode;
+  executionMode: "standard" | "strict";
+  idempotencyKey: string;
+  specHash: string;
+  policyHash?: string;
+  generatedAt: string;
+  checks: AutomationPreflightCheck[];
+  summary: {
+    pass: number;
+    warn: number;
+    fail: number;
+    skipped: number;
+    highestSeverity: AutomationPreflightSeverity;
+    firstFailure?: Pick<AutomationPreflightCheck, "id" | "domain" | "classification" | "summary" | "remediation">;
+  };
+};
+```
+
+Required check domains:
+
+- `spec`: parse workflow JSON, canonicalize prompt file references, validate
+  command/action binding, enforce no embedded secrets in target env/prompt
+  metadata, and return the stable `specHash`.
+- `provider`: verify provider name, executable binding, provider capability
+  support, prompt delivery mode, and bounded subprocess preflight for binaries
+  only.
+- `account`: resolve Codewith `authProfile` or OpenAccounts `{profile, tool}`
+  refs, record profile/tool names only, and fail when the profile is missing or
+  the profile directory cannot be resolved.
+- `command`: validate command targets with `shell=false` executable rules,
+  `preflightAnyOf`, and planned allow-command enforcement before execution.
+- `secret`: check required secret refs by ref/name and owner response only;
+  never place secret values, exported env, or raw secret-manager payloads in the
+  result.
+- `connector`: ask the owning action/connector system whether the connector
+  credential handle exists, is scoped for the source action, and is usable; do
+  not make OpenLoops the connector credential store.
+- `permissions`: reject unsafe `permissionMode="bypass"`, unsafe
+  `configIsolation="none"`, mutable command targets without an explicit policy,
+  or missing approval evidence when strict automation requires it.
+- `sandbox`: verify provider-native sandbox support and reject strict mode when
+  requested sandboxing cannot be proven.
+- `worktree`: require `worktree.mode="required"` for repo mutation in strict
+  mode and verify worktree metadata contains repo root, path, branch, original
+  cwd, and target cwd without preparing the worktree during pure preflight.
+- `machine`: check requested machine route, local/remote confidence, and remote
+  bootstrap availability; fail a strict request when the route does not match
+  the workflow scope.
+- `allowlist`: in standard mode, preserve current `metadata_only` behavior as a
+  warning; in strict mode, fail unless command/tool allowlist enforcement can be
+  proven for every step that requests it.
+- `redaction`: prove the result was built through the redaction policy that will
+  be used for persistence and manifests.
+- `evidence`: include durable refs when available and enough context for the
+  caller to inspect the follow-on run without querying SQLite directly.
+
+Preflight must be side-effect bounded:
+
+- `dry-run` performs schema validation, canonicalization, policy normalization,
+  and hashing only. It must not create a database file in an empty data dir and
+  must not spawn account/provider probes.
+- `preflight` may run bounded local or remote readiness probes such as
+  `command -v`, `accounts env <profile> --tool <tool>`, provider profile-list
+  checks, and connector readiness calls owned by the automation/action system.
+  It must not run target commands, dispatch agents, create workflows or loops,
+  write task comments, prepare worktrees, or mutate queue state.
+- `commit` is idempotent. In strict mode it must run or reuse a fresh compatible
+  preflight result before storing or dispatching. In standard mode it may attach
+  warnings without changing current execution defaults.
+
+Strict-mode failures are fail-closed for missing account profiles, missing
+connector auth, missing required secret refs, unsupported sandbox posture,
+unsupported provider allowlist enforcement, bypass permissions, non-required
+worktrees for repo mutation, missing prompt files, and machine route mismatch.
+
+## Planned Compact Evidence API
+
+Every public surface should expose the same compact evidence shape so callers
+can hand results across `@hasna/actions`, `@hasna/automations`, OpenLoops route
+drains, MCP tools, and CLI scripts without scraping SQLite or leaking secrets.
+
+```ts
+type AutomationEvidenceRef = {
+  workflowId?: string;
+  loopId?: string;
+  invocationId?: string;
+  workItemId?: string;
+  runId?: string;
+  manifestPath?: string;
+  external?: Array<{ system: "actions" | "automations" | "connector" | string; ref: string }>;
+};
+
+type AutomationEvidenceSummary = {
+  version: 1;
+  kind: "workflow-upsert" | "preflight" | "route-admission" | "workflow-run";
+  generatedAt: string;
+  source: { kind: string; id: string; dedupeKey?: string };
+  subject: { kind: string; id?: string; path?: string; url?: string };
+  refs: AutomationEvidenceRef;
+  specHash: string;
+  policyHash?: string;
+  executionMode: "standard" | "strict";
+  dispatch: "schedule" | "run-now" | "none";
+  status: "accepted" | "reused" | "rejected" | "running" | "succeeded" | "failed" | "dead_letter";
+  preflight?: {
+    ok: boolean;
+    counts: AutomationPreflightResult["summary"];
+    failedCheckIds: string[];
+    warningCheckIds: string[];
+  };
+  redactionProfile: "default" | "strict";
+  redacted: true;
+};
+```
+
+Persistence and output rules:
+
+- CLI `--json`, SDK results, MCP tool results, route dry-run output, route work
+  item evidence, and workflow run manifests all return `AutomationEvidenceSummary`
+  plus optional full `AutomationPreflightResult` when the caller explicitly asks
+  for preflight detail.
+- Evidence contains names, refs, hashes, status, classifications, counts, and
+  remediation hints only. It never contains secret values, full env maps, raw
+  connector/provider payloads, private prompt text, stdout/stderr dumps, or
+  unsanitized errors.
+- `manifestPath` is the filesystem ref for durable evidence, but the compact
+  summary must be enough for a normal caller to find the workflow, loop, run,
+  work item, and owning external action/automation refs through public APIs.
+- Failed preflight evidence should be persistable when a commit attempt is
+  rejected, but pure `dry-run`/`preflight` calls should return it directly
+  without creating OpenLoops database rows.
+- Redaction happens before persistence and before API return. Tests should
+  exercise both flat secret-looking text and nested JSON evidence values.
+
+Implementation should expose the contract incrementally:
+
+1. Add shared types and a pure result builder that converts validator outcomes
+   into `AutomationPreflightCheck` entries.
+2. Wrap existing `preflightTarget`/`preflightWorkflow` with aggregate result
+   builders while keeping the current throwing APIs for compatibility.
+3. Add `loops workflows upsert-one-shot --mode dry-run|preflight|commit --json`
+   and SDK equivalents that return `WorkflowUpsertResult`.
+4. Thread compact evidence through route dry-runs, admitted work items, workflow
+   run manifests, MCP workflow validation, and the HTTP API.
+5. Add strict-mode enforcement only after provider allowlist and secret/connector
+   readiness adapters can prove enforcement without leaking payloads.
+
+Expected validation for that future implementation: focused unit tests for
+workflow parsing, executor preflight, route dry-run output, run manifests,
+redaction, SDK/CLI/MCP/API JSON shape, then `bun run typecheck`, `bun test`,
+`bun run build`, and `bun run test:boundary`.
+
 ## Planned Strict Automation Execution
 
 Automation-generated targets need a stricter execution mode than ordinary local

package/docs/CUTOVER-RUNBOOK.md

@@ -1,61 +1,78 @@
 # Loops Postgres Cutover Runbook
 
-Status: **backend foundation landed; daemon still runs on local sqlite.** Do NOT
-flip the running daemon to Postgres until every step below is green.
-
-PURE REMOTE (Amendment A1): in cloud mode, reads AND writes hit cloud Postgres
-directly. There is no hybrid/sync/cache mode. After a verified migration the
-local sqlite file is renamed to `<name>.db.pre-cloud-2026-07-06.bak`.
-
-## What shipped in this PR
-
-- Vendored `@hasna/contracts` storage kit → `src/generated/storage-kit/`
-  (pool/query/tls/mode/migrations/health). Regenerate: `bunx @hasna/contracts vendor-kit`.
-- `src/lib/storage/pg-executor.ts` — `PgPoolExecutor` adapting the vendored
-  `pg.Pool` client to `PostgresQueryExecutor` (drives `PostgresStorage.migrate`).
-- `src/lib/storage/pg-runner-claim.ts` — `claimNextRun` / `heartbeatRunLease`
-  using `SELECT ... FOR UPDATE SKIP LOCKED` for concurrent runners.
-- `src/lib/storage/postgres-concurrency.test.ts` — two-connection race test
-  (skips unless `LOOPS_TEST_DATABASE_URL` is set; verified green against a
-  throwaway local Postgres 16).
-- `pg` promoted to a direct dependency; `@types/pg` added as devDependency.
-
-## Remaining before daemon cutover (tracked, NOT done here)
-
-1. **Full `PostgresLoopStorage` implementing `LoopStorageContract`** (60+ methods
-   in `src/lib/storage/contract.ts`). Only the migration ledger + claim/lease
-   primitives exist today. The claim primitive here is the correctness core to
-   build the rest on.
-2. **Async consumer wiring.** All call sites construct `new Store()` synchronously
-   (`src/cli`, `src/daemon`, `src/sdk`, `src/mcp`, `src/lib/route`). PURE REMOTE
-   requires routing them through the async `LoopStorageContract` when
-   `LOOPS_DATABASE_URL` is set (mode resolved by `src/lib/mode.ts`, which stays
-   authoritative). `SqliteLoopStorage` already wraps the sync store for the
-   local path.
-3. **`loops migrate-local` command** (data migration TOOLING only): copy
-   definitions + schedules + last 30 days of runs from local sqlite into cloud
-   Postgres, then rename the sqlite file to the `.pre-cloud-2026-07-06.bak`
-   backup. Does NOT enable cloud mode.
-4. **Apply schema to shared RDS** via SSM tunnel on local port 15438 using the
-   `hasna/oss/loops/database-url-owner` secret, then run
-   `PostgresStorage(new PgPoolExecutor(...)).migrate()` (dry-run first). Kill the
-   tunnel and remove temp files afterward. Never run the test suite against RDS.
-
-## Enable steps (run only after 1–4 are green)
-
-1. Confirm `PostgresStorage.migrate({ dryRun: true })` reports all four
-   migrations already applied on the loops RDS database.
-2. Stop the loops daemon: `loops daemon stop`.
-3. `loops migrate-local --database-url "$LOOPS_DATABASE_URL"` (moves defs +
-   schedules + 30d of runs; verify counts; sqlite renamed to backup).
-4. Export `LOOPS_DATABASE_URL` (from `hasna/oss/loops/database-url`) and the
-   cloud storage-mode env for the daemon unit; restart the daemon.
-5. Verify `loops status` reports `deploymentMode: cloud`, `sourceOfTruth:
-   cloud_control_plane`, and that a test loop run claims + finalizes against
-   Postgres.
+Status: **self-hosted control-plane backend landed; local daemon cutover is not
+complete.** Do not flip scheduled production execution away from local SQLite
+until the runner and migration follow-ups below are green.
+
+Deployment vocabulary: `self_hosted` is the Hasna-owned AWS/RDS control-plane
+deployment. `cloud` is the future hosted SaaS contract for outside users. The
+vendored `@hasna/contracts` storage kit still calls direct Postgres storage
+mode `cloud`; treat that as a storage-kit implementation term, not the
+OpenLoops deployment mode.
+
+## What Shipped
+
+- `loops-serve` HTTP control plane: RDS-direct Postgres, `GET /health`,
+  `/ready`, `/version`, `/openapi.json`, storage-backed `/v1` loop CRUD and run
+  listing, and runner registration/claim/heartbeat/finalize protocol routes.
+- `@hasna/contracts` API-key auth on non-local `loops-serve` binds, backed by
+  the shared `api_keys` table and a signing secret.
+- Full `PostgresLoopStorage` behind `LoopStorageContract`, plus
+  `PgPoolExecutor`, runner claim/lease helpers, and Postgres concurrency tests.
+- `loops-serve migrate`, which applies the ledger-tracked Postgres migrations
+  and ensures the `api_keys` table.
+- `@hasna/loops/sdk/http`, generated from `openapi/loops.json`.
+- ARM64/Bun `Dockerfile`, local `docker-compose.yml`, `hasna.contract.json`,
+  and a generated `migrations/` mirror for review.
+
+## Local Postgres Smoke For loops-serve
+
+Run the local development stack for the self-hosted service:
+
+```bash
+docker compose run --rm loops-migrate
+docker compose up --build loops-serve
+curl -fsS http://127.0.0.1:8787/health
+curl -fsS http://127.0.0.1:8787/ready
+curl -fsS http://127.0.0.1:8787/openapi.json
+```
+
+`loops-serve` may bind to loopback without an API signing secret for local
+development. A non-local bind must set `HASNA_LOOPS_API_SIGNING_KEY`,
+`HASNA_API_SIGNING_KEY`, or `API_KEY_SIGNING_SECRET`; otherwise the service
+fails closed before exposing `/v1`.
+
+## AWS Self-Hosted Gates
+
+1. Apply migrations with the ECS one-shot task or an operator command:
+   `HASNA_LOOPS_DATABASE_URL=... loops-serve migrate --dry-run`, then
+   `HASNA_LOOPS_DATABASE_URL=... loops-serve migrate`.
+2. Start `loops-serve` with `HASNA_LOOPS_MODE=self_hosted`,
+   `HASNA_LOOPS_DATABASE_URL`, and the API signing secret from the approved
+   vault item. Do not log or copy the secret value into task evidence.
+3. Verify `/health`, `/ready`, `/version`, and `/openapi.json`.
+4. Verify an authenticated `/v1` read/write smoke against a throwaway loop and
+   a runner registration/claim/finalize smoke if a runner API URL is configured.
+5. Record package version, git SHA, image tag, database migration plan/result,
+   redacted API URL, health/readiness responses, and rollback handle.
+
+## Still Pending Before Daemon Cutover
+
+- Long-running `loops-runner` daemon mode with backoff, fleet observability, and
+  durable machine registration records.
+- Workflow target execution over the runner protocol.
+- Id-preserving self-hosted import endpoints for workflow specs, loop
+  definitions, run history, workflow history, work items, goals, and audit rows.
+- A no-loss migration path from local SQLite into the self-hosted control plane.
+  Current `loops export`/`loops import` are local-store tools, and
+  `loops self-hosted migrate|push|pull` remain previews.
+- Hosted SaaS integration outside this public package.
 
 ## Rollback
 
-Cloud mode is off until `LOOPS_DATABASE_URL` is present in the daemon env.
-To roll back: unset it, restore the sqlite backup
-(`mv <name>.db.pre-cloud-2026-07-06.bak <name>.db`), restart the daemon.
+For the self-hosted service, roll back by moving traffic to the previous image
+or stopping the new `loops-serve` task. Local scheduled execution remains on
+SQLite unless operators explicitly configure a runner/control-plane cutover, so
+removing `LOOPS_API_URL`, `HASNA_LOOPS_API_URL`, `LOOPS_DATABASE_URL`, or
+`HASNA_LOOPS_DATABASE_URL` returns the standalone CLI/daemon perspective to
+`local`.