@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

package/apps/storefront/src/lib/d1/schema-apps.ts

@@ -1,9 +1,8 @@
 /**
  * Drizzle schema — the source of truth for `STOREFRONT_APPS_DB` *migration
- * generation* (ADR-0002). Split out of `schema.ts` (which now covers only the
- * catalog + customization tables on `CATALOG_DB`): these tables are the
- * storefront-apps registry/webhooks/orders spine and belong to a DEDICATED
- * D1, never the catalog.
+ * generation*. `schema.ts` covers the catalog + customization tables on
+ * `CATALOG_DB`; these tables are the storefront-apps registry/webhooks/orders
+ * spine and belong to a DEDICATED D1, never the catalog.
  *
  * `drizzle-kit generate --config drizzle.config.apps.ts` diffs this into
  * numbered SQL under `migrations-apps/`, applied by `wrangler d1 migrations
@@ -11,8 +10,8 @@
  */
 import { sqliteTable, text, integer, real, index, uniqueIndex, primaryKey } from "drizzle-orm/sqlite-core";
 
-// --- Private Apps registry (PrivateApps epic, D2) ----------------------------
-// One install per (app, tenant, env). `installId` is the future JWT `sub`.
+// --- Private Apps registry --------------------------------------------------
+// One install per (app, tenant, env). `installId` is the JWT `sub`.
 // Append-only `app_audit_log` is never pruned by the service layer.
 export const appInstalls = sqliteTable(
   "app_installs",
@@ -28,6 +27,14 @@ export const appInstalls = sqliteTable(
     webhookEndpoint: text("webhook_endpoint"),
     widgetPlacements: text("widget_placements").notNull().default("[]"),
     installActor: text("install_actor").notNull(),
+    // Nullable discriminator keeps the managed-analytics v1 lifecycle on the
+    // canonical install row instead of creating a second install authority.
+    managedKind: text("managed_kind"),
+    managedRevision: integer("managed_revision").notNull().default(0),
+    managedActiveRevisionId: text("managed_active_revision_id"),
+    // Validated non-live candidate only. Live effects remain in manifest and
+    // app_version_snapshots, the registry's established serving authorities.
+    managedCandidate: text("managed_candidate"),
     createdAt: text("created_at").notNull(),
     updatedAt: text("updated_at").notNull(),
   },
@@ -71,14 +78,31 @@ export const appAuditLog = sqliteTable(
   }),
 );
 
-// --- Operational activity timeline (activity-telemetry epic, card D4) --------
+// Inert reviewed migration suggestions. This is deliberately NOT an install,
+// live effect, revision, or publish authority; conversion requires a separate
+// canonical `app_installs` mutation and drafts can never be enabled.
+export const integrationMigrationDrafts = sqliteTable(
+  "integration_migration_drafts",
+  {
+    draftId: text("draft_id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    revision: integer("revision").notNull(),
+    state: text("state").notNull().default("open"),
+    record: text("record").notNull(),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({ idxIntegrationMigrationDraftsTenant: index("idx_integration_migration_drafts_tenant").on(t.tenantId, t.createdAt) }),
+);
+
+// --- Operational activity timeline ------------------------------------------
 // The low-volume / high-value LIFECYCLE cohort of the actor×action telemetry
 // spine (DECISIONS.md §8). Only actions whose catalog `spec.sinks` include
 // "timeline" land here; the high-volume cohort goes to Cloudflare Analytics
 // Engine (binding `ACTIVITY_ANALYTICS`), and EVERY action also goes to Workers
 // Logs. Reuses the EXISTING STOREFRONT_APPS_DB (precedent: `app_audit_log`
 // above) rather than a new binding — the cohort is small (~50k rows/month at
-// 10× pilot) and the D5 query UI needs point queries + joins + arbitrary
+// 10× pilot) and the timeline query UI needs point queries + joins + arbitrary
 // retention that Analytics Engine cannot give.
 //
 // `id` is the emitter-minted event UUID and the PRIMARY KEY, so a retried/
@@ -116,7 +140,7 @@ export const activityEvents = sqliteTable(
     ingestedAt: text("ingested_at").notNull(),
   },
   (t) => ({
-    // The D5 timeline query: a tenant's events newest-first.
+    // The timeline query: a tenant's events newest-first.
     idxActivityTenantAt: index("idx_activity_tenant_at").on(t.tenantId, t.at),
     // Filter a tenant's timeline by action family (dashboards glob the prefix).
     idxActivityTenantAction: index("idx_activity_tenant_action").on(t.tenantId, t.action),
@@ -125,7 +149,7 @@ export const activityEvents = sqliteTable(
   }),
 );
 
-// --- Webhook event spine (PrivateApps epic, D4 Chunk A) ---------------------
+// --- Webhook event spine ----------------------------------------------------
 // Immutable event log. `id` is the semantic event id we mint — distinct from
 // any per-delivery wire envelope id (see `webhookDeliveries.deliveryId` below).
 export const webhookEvents = sqliteTable("webhook_events", {
@@ -195,10 +219,10 @@ export const webhookInstallHealth = sqliteTable("webhook_install_health", {
   updatedAt: text("updated_at").notNull(),
 });
 
-// --- Order ingestion (PrivateApps epic, D6 Chunk A) --------------------------
+// --- Order ingestion --------------------------------------------------------
 // The read-model `ordersStore.ts` diffs incoming Foxy orders against (created
-// → fulfilled transitions, for a later chunk's event emission) and that the
-// attribution route (also later) reads from for its cross-tenant ownership
+// → fulfilled transitions, for event emission) and that the
+// attribution route reads from for its cross-tenant ownership
 // check. `(tenantId, externalOrderId)` is the composite PK — same "no
 // synthetic id, the natural key IS the key" style as `customizationVersions`
 // (schema.ts) — no SQL FK to `appAttributions.orderId` (repo convention — code-only).
@@ -225,7 +249,7 @@ export const orders = sqliteTable(
   }),
 );
 
-// First idempotency ledger in the codebase (D6 Chunk A) — keyed per
+// The idempotency ledger — keyed per
 // `(installId, idempotencyKey)` so a retried write (e.g. attribution POST)
 // replays the stored `responseBody` instead of re-applying the mutation.
 // `bodyHash` (sha256 of the canonical request body) lets a caller re-sending
@@ -242,9 +266,38 @@ export const idempotencyKeys = sqliteTable(
   (t) => ({ pk: primaryKey({ columns: [t.installId, t.idempotencyKey] }) }),
 );
 
-// App-owned attribution/commission records (`attribution:write`, D6 — later
-// chunk owns the route). `orderId` references `orders.externalOrderId` in code
-// only (no SQL FK, repo convention); the route chunk enforces the cross-tenant
+// --- Encrypted outbound social OAuth tokens ---------------------------------
+// The ONLY retrievable secret store in this codebase: per-`(tenant, network)`
+// OAuth access/refresh tokens we must REPLAY to X/LinkedIn, so — unlike the
+// one-way-hashed `app_credentials` above — they are stored ENCRYPTED-AT-REST,
+// not hashed. `ciphertext` is AES-GCM(base64) over the JSON token payload and
+// `iv` its per-write 96-bit nonce (base64); the key-encryption-key (KEK) is a
+// Worker env binding (`SOCIAL_TOKEN_KEK`), NEVER a column here — mirroring how
+// every other real secret in this codebase is an env binding, not row data.
+// Composite PK `(tenant_id, network)` is the natural key (same "the natural key
+// IS the key" style as `orders`); a rotate is an INSERT OR REPLACE overwrite.
+// `expires_at` is the token's own OAuth expiry (nullable — long-lived manual
+// creds have none), distinct from the row's `updated_at` bookkeeping clock.
+export const socialTokens = sqliteTable(
+  "social_tokens",
+  {
+    tenantId: text("tenant_id").notNull(),
+    network: text("network").notNull(),
+    ciphertext: text("ciphertext").notNull(),
+    iv: text("iv").notNull(),
+    expiresAt: text("expires_at"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.tenantId, t.network] }),
+    idxSocialTokensTenant: index("idx_social_tokens_tenant").on(t.tenantId),
+  }),
+);
+
+// App-owned attribution/commission records (`attribution:write`). `orderId`
+// references `orders.externalOrderId` in code
+// only (no SQL FK, repo convention); the route enforces the cross-tenant
 // ownership check the contract requires before ever writing a row here.
 export const appAttributions = sqliteTable(
   "app_attributions",
@@ -265,3 +318,305 @@ export const appAttributions = sqliteTable(
     idxAppAttributionsTenantOrder: index("idx_app_attributions_tenant_order").on(t.tenantId, t.orderId),
   }),
 );
+
+// --- Newsletter subscribers -------------------------------------------------
+// First-party audience for the blog/newsletter digest, kept in OUR D1 (not a
+// vendor list) so the per-tenant isolation + GDPR data-control invariants stay
+// under our control.
+// `tenantId` is the isolation boundary, written from the resolved host/session
+// — NEVER a client body. Keyed on `(tenant_id, collection, email)` so a tenant
+// with multiple collections (e.g. `blog` + `the-build`) runs independent lists.
+// `token` is an opaque random used for both confirm + one-click unsubscribe
+// links; `consentIpHash` is sha256(ip+salt) — never a raw IP (PII). Timestamps
+// are ISO-8601 text. `status`: pending | confirmed | unsubscribed | bounced.
+export const newsletterSubscribers = sqliteTable(
+  "newsletter_subscribers",
+  {
+    tenantId: text("tenant_id").notNull(),
+    collection: text("collection").notNull(),
+    email: text("email").notNull(),
+    status: text("status").notNull().default("pending"),
+    token: text("token").notNull(),
+    consentSource: text("consent_source"),
+    consentIpHash: text("consent_ip_hash"),
+    subscribedAt: text("subscribed_at").notNull(),
+    confirmedAt: text("confirmed_at"),
+    unsubscribedAt: text("unsubscribed_at"),
+    lastSentAt: text("last_sent_at"),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.tenantId, t.collection, t.email] }),
+    idxNewsletterTenantCollStatus: index("idx_newsletter_tenant_coll_status").on(
+      t.tenantId,
+      t.collection,
+      t.status,
+    ),
+  }),
+);
+
+// Idempotent per-digest send log so a re-triggered digest can't double-send.
+// Keyed on `(tenant_id, collection, digest_id)` (e.g. `the-build-2026-W34`);
+// `postSlugs` is a JSON array of the slugs included in that digest.
+export const newsletterSends = sqliteTable(
+  "newsletter_sends",
+  {
+    tenantId: text("tenant_id").notNull(),
+    collection: text("collection").notNull(),
+    digestId: text("digest_id").notNull(),
+    postSlugs: text("post_slugs").notNull().default("[]"),
+    recipientCount: integer("recipient_count").notNull().default(0),
+    sentAt: text("sent_at").notNull(),
+  },
+  (t) => ({ pk: primaryKey({ columns: [t.tenantId, t.collection, t.digestId] }) }),
+);
+
+// --- Canonical publish-candidate identity -----------------------------------
+// ONE canonical candidate per `(tenant_id, repository, pr_number)` — the real
+// forge PR. Retries/rebuilds are NOT new candidates; they are child `attempts`
+// (below). This is the durable identity spine other units resolve against; the
+// KV `ReviewEnvironment` (`cust:*`) and aggregate/release models (`rel:*`) are
+// read projections that reference this row's `change_id`/`pr_number`.
+//
+// `id` is a SYNTHETIC surrogate (`cand_<uuid>`), deliberately DISTINCT from the
+// canonical key so foreign keys (attempts) never depend on the mutable natural
+// key. `change_id` is the REAL forge change id — the stable branch/build
+// identity (`candidate/<change_id>`) — preserved, never derived from `id`.
+// `tenant_id` is the isolation boundary, written from the resolved session,
+// NEVER a client body. The UNIQUE `(tenant_id, repository, pr_number)` is what
+// makes "one candidate per PR" a schema invariant (upsert-by-key, not
+// insert-then-dedupe); the UNIQUE `(tenant_id, change_id)` keeps the branch/
+// build identity unambiguous for resolve-by-changeId callers.
+export const candidates = sqliteTable(
+  "candidates",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    // The `<tenant>-<tag>` forge repository the PR lives in.
+    repository: text("repository").notNull(),
+    // The forge PR number — the third leg of the canonical key.
+    prNumber: integer("pr_number").notNull(),
+    // The real forge change id — stable branch/build identity (`candidate/<change_id>`).
+    changeId: text("change_id").notNull(),
+    // Source branch, conventionally `candidate/<change_id>` (nullable convenience mirror).
+    branch: text("branch"),
+    title: text("title"),
+    author: text("author"),
+    // Canonical candidate lifecycle: open | preparing | ready | needs-attention | accepted | rejected | closed.
+    status: text("status").notNull().default("open"),
+    // The PR head/base shas as last reconciled (nullable until first read).
+    headSha: text("head_sha"),
+    baseSha: text("base_sha"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+  },
+  (t) => ({
+    uqCandidatesCanonical: uniqueIndex("uq_candidates_tenant_repo_pr").on(
+      t.tenantId,
+      t.repository,
+      t.prNumber,
+    ),
+    uqCandidatesChange: uniqueIndex("uq_candidates_tenant_change").on(t.tenantId, t.changeId),
+    idxCandidatesTenantStatus: index("idx_candidates_tenant_status").on(t.tenantId, t.status),
+  }),
+);
+
+// One `attempt` = one build/check/rebase EXECUTION of a candidate. Attempts are
+// the child rows retries produce — they must NEVER queue as separate top-level
+// candidate rows. `candidate_id` references `candidates.id` in code only (no SQL
+// FK — repo convention, matches `webhook_deliveries.event_id` / `orders`).
+// `tenant_id` is denormalized for tenant-scoped reads/isolation without a join.
+// `attempt_number` is monotonic per candidate (1,2,3…) giving stable ordering;
+// UNIQUE `(candidate_id, attempt_number)` makes a double-assigned number a loud
+// failure rather than a silent duplicate. `kind`: build | check | rebase;
+// `status`: pending | running | passed | failed | cancelled (mirrors
+// `IntegrationRun`'s state vocabulary). `evidence` is a JSON EvidenceReport
+// snapshot; `detail` a human-legible terminal-state message.
+export const candidateAttempts = sqliteTable(
+  "candidate_attempts",
+  {
+    id: text("id").primaryKey(),
+    candidateId: text("candidate_id").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    attemptNumber: integer("attempt_number").notNull(),
+    kind: text("kind").notNull(),
+    status: text("status").notNull().default("pending"),
+    // The candidate head sha this attempt executed against, or null if unknown.
+    headSha: text("head_sha"),
+    detail: text("detail"),
+    evidence: text("evidence"),
+    startedAt: text("started_at").notNull(),
+    // Null while pending/running; set on a terminal transition.
+    finishedAt: text("finished_at"),
+  },
+  (t) => ({
+    uqAttemptNumber: uniqueIndex("uq_candidate_attempts_candidate_number").on(
+      t.candidateId,
+      t.attemptNumber,
+    ),
+    idxAttemptsCandidate: index("idx_candidate_attempts_candidate").on(t.candidateId),
+    idxAttemptsTenant: index("idx_candidate_attempts_tenant").on(t.tenantId),
+  }),
+);
+
+// One active submit per tenant/change. This serializes identity authorization,
+// the Gitea mutation, and audit finalization so a verified callback cannot
+// become stale between its forge read and its KV writes. `expires_at` is
+// diagnostic only; recovery is explicit so a slow live submit cannot be
+// time-fenced incorrectly.
+export const candidateSubmitLeases = sqliteTable(
+  "candidate_submit_leases",
+  {
+    tenantId: text("tenant_id").notNull(),
+    changeId: text("change_id").notNull(),
+    authorizationId: text("authorization_id").notNull(),
+    status: text("status").notNull().default("active"),
+    acquiredAt: text("acquired_at").notNull(),
+    expiresAt: text("expires_at").notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.tenantId, t.changeId] }),
+    idxExpires: index("idx_candidate_submit_leases_expires").on(t.expiresAt),
+  }),
+);
+
+// --- Merchant consent configuration -----------------------------------------
+// APPEND-ONLY revision history of a tenant's consent configuration (the
+// ext-admin-03 surface that feeds the ext-policy-03 broker). Each save is a NEW
+// immutable row — the current config is `MAX(revision)` per tenant — so the table
+// IS the audit trail (actor + timestamp per revision, never mutated in place) and
+// a revert is a forward-only new revision that copies a prior `config` and records
+// `reverted_from`. `config` is the JSON `TenantConsentConfig` (never secret-bearing
+// — consent config carries no secrets). `tenant_id` is the isolation boundary,
+// written from the resolved session, never a client body. UNIQUE
+// `(tenant_id, revision)` makes the monotonic revision a schema invariant.
+export const consentConfigRevisions = sqliteTable(
+  "consent_config_revisions",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    // Monotonic per tenant (1, 2, 3…) — the latest revision is the current config.
+    revision: integer("revision").notNull(),
+    // The JSON-serialized validated `TenantConsentConfig`.
+    config: text("config").notNull(),
+    // Opaque actor id — never email/PII (matches `app_audit_log`).
+    actor: text("actor").notNull(),
+    // Human-legible note (e.g. the reason, or "revert to revision N").
+    note: text("note"),
+    // When this revision copies an earlier one, the source revision — else null.
+    revertedFrom: integer("reverted_from"),
+    createdAt: text("created_at").notNull(),
+  },
+  (t) => ({
+    uqConsentConfigTenantRevision: uniqueIndex("uq_consent_config_tenant_revision").on(
+      t.tenantId,
+      t.revision,
+    ),
+    idxConsentConfigTenant: index("idx_consent_config_tenant").on(t.tenantId),
+  }),
+);
+
+// Demonstrated CMP demand — one row per `(tenant, adapter)` demand signal. The set
+// of SELECTABLE CMP adapters is DERIVED from these rows (distinct-tenant count over
+// a threshold), never a hardcoded catalog: the first CMP Storefront adapts is
+// whichever real demand first proves (ADR 0014 P2 / 0025). UNIQUE
+// `(tenant_id, adapter_id)` makes demand a per-tenant fact (a tenant re-asking does
+// not inflate the count); the `adapter_id` index serves the per-adapter rollup.
+export const consentCmpDemand = sqliteTable(
+  "consent_cmp_demand",
+  {
+    id: text("id").primaryKey(),
+    tenantId: text("tenant_id").notNull(),
+    adapterId: text("adapter_id").notNull(),
+    // Where the demand came from (a merchant request, a support ticket), for the record.
+    source: text("source"),
+    at: text("at").notNull(),
+  },
+  (t) => ({
+    uqConsentCmpDemandTenantAdapter: uniqueIndex("uq_consent_cmp_demand_tenant_adapter").on(
+      t.tenantId,
+      t.adapterId,
+    ),
+    idxConsentCmpDemandAdapter: index("idx_consent_cmp_demand_adapter").on(t.adapterId),
+  }),
+);
+
+// --- Commerce conversion attribution (ext-commerce-04) -----------------------
+// The single-use ledger for the signed checkout-correlation token's `jti`
+// (`packages/public-runtime/src/integration/correlation-token.ts`). The order join
+// consumes a token EXACTLY once: a replay of a consumed `jti` is refused. `jti` is
+// the natural key (the token's own 96-bit nonce); `expires_at` is the token's Unix-
+// seconds `exp` so a consumed row can be pruned once the token is already `expired`
+// (a past-`exp` token is rejected before the guard is even reached). Carries no PII
+// and no secret — the `jti` is an opaque nonce, never the token or the signing key.
+export const correlationReplay = sqliteTable("correlation_replay", {
+  jti: text("jti").primaryKey(),
+  expiresAt: integer("expires_at").notNull(),
+  consumedAt: text("consumed_at").notNull(),
+});
+
+// --- Retained managed-app version facets (ext-apps-02) -----------------------
+// APPEND-ONLY retention of every activated managed-app VERSION's COMPLETE
+// restorable facet set, and the atomic-rollback spine over it. One row per
+// activation of an install; the CURRENT active version is `MAX(seq)` per install
+// (same "the latest row is current" model as `consent_config_revisions`). The
+// whole restorable facet set (code ref/digest, entry module, public config,
+// contributions, granted scopes, consent declaration, CSP origins) is one JSON
+// blob in `facets` — so retaining a version and rolling one back are each a
+// SINGLE-ROW insert: the restore is atomic by construction (you get the whole
+// prior facet set or nothing — never a partial/mixed activation). A rollback is
+// forward-only: it appends a NEW activation copying a retained version's facets
+// and records `restored_from_seq`, so history is never rewritten and the rollback
+// is itself an audited row. `tenant_id` is the isolation boundary, denormalized
+// for tenant-scoped reads (no SQL FK — repo convention). `facets` carries no
+// secret material (proved by the ext-kernel-01 secret scan before insert). UNIQUE
+// `(install_id, seq)` makes the monotonic sequence a schema invariant.
+export const appVersionSnapshots = sqliteTable(
+  "app_version_snapshots",
+  {
+    id: text("id").primaryKey(),
+    installId: text("install_id").notNull(),
+    tenantId: text("tenant_id").notNull(),
+    // Monotonic per install (1, 2, 3…); the largest is the active version.
+    seq: integer("seq").notNull(),
+    // The app package version this activation serves (mirror of facets.appVersion).
+    appVersion: text("app_version").notNull(),
+    // The complete restorable facet set as one JSON blob (AppVersionFacets).
+    facets: text("facets").notNull(),
+    // Opaque actor id — never email/PII (matches `app_audit_log`).
+    actor: text("actor").notNull(),
+    // Human-legible note (e.g. the reason, or "rollback to version N").
+    note: text("note"),
+    // When this activation restores an earlier one, its source `seq` — else null.
+    restoredFromSeq: integer("restored_from_seq"),
+    createdAt: text("created_at").notNull(),
+  },
+  (t) => ({
+    uqAppVersionSnapshotsInstallSeq: uniqueIndex("uq_app_version_snapshots_install_seq").on(
+      t.installId,
+      t.seq,
+    ),
+    idxAppVersionSnapshotsInstall: index("idx_app_version_snapshots_install").on(t.installId),
+  }),
+);
+
+// The per-`(tenant, external_order_id)` attribution ledger. An order's attribution is
+// decided ONCE (on its first `order.created`/`order.fulfilled` conversion) and reused
+// for every later lifecycle conversion, so the correlation `jti` is consumed once per
+// order — not once per lifecycle event — and a duplicate/replayed/out-of-order webhook
+// reproduces the same outcome. `attributed` is 0/1; when attributed, `correlation_id`
+// + `correlation_expires_at` hold the shared thread; when not, `reason` records why
+// (missing/expired/context_mismatch/replay/…). Never customer identity — only the
+// opaque correlation handle. `(tenant_id, external_order_id)` is the natural key.
+export const orderAttribution = sqliteTable(
+  "order_attribution",
+  {
+    tenantId: text("tenant_id").notNull(),
+    externalOrderId: text("external_order_id").notNull(),
+    attributed: integer("attributed").notNull().default(0),
+    correlationId: text("correlation_id"),
+    correlationExpiresAt: text("correlation_expires_at"),
+    reason: text("reason"),
+    recordedAt: text("recorded_at").notNull(),
+  },
+  (t) => ({ pk: primaryKey({ columns: [t.tenantId, t.externalOrderId] }) }),
+);

package/apps/storefront/src/lib/dev/activityIngestToken.ts

@@ -1,8 +1,7 @@
 /**
  * Opaque, SESSION-KV-backed credential that lets a developer's LOCAL dev-loop
  * process authenticate POST /api/dev/activity on the hosted Worker — the
- * local→hosted activity bridge (handoff
- * 2026-07-14-hosted-dev-activity-bridge-and-stepper).
+ * local→hosted activity bridge.
  *
  * Minted alongside the existing cli-signin-code paste
  * (apps/storefront/src/lib/dev/cliSignInCode.ts) and cached by the CLI in
@@ -30,8 +29,7 @@ export interface ActivityIngestClaims {
    * sign-in code was issued (see api/dev/cli-signin-code.ts). It rides in the
    * claims so every runtime/activity write the local loop makes with this token
    * is stampable with the same id — support looks a live session up by it.
-   * Optional so tokens minted before this field existed still verify (they just
-   * carry no trace); every freshly-minted token sets it.
+   * Optional: a token without it carries no trace; every freshly-minted token sets it.
    */
   traceId?: string;
 }

package/apps/storefront/src/lib/dev/activityStore.ts

@@ -1,9 +1,8 @@
 /**
  * Per-vendor "recent activity" feed for the hosted /dev panel — a small ring
  * buffer of file-save events reported by a developer's LOCAL dev loop (see
- * activityIngestToken.ts for the write-path auth). File-level only, per
- * decision (no per-line diff, no separate published-history tier — see
- * handoff 2026-07-14-hosted-dev-activity-bridge-and-stepper).
+ * activityIngestToken.ts for the write-path auth). File-level only: no
+ * per-line diff, no separate published-history tier.
  */
 
 export type ActivityEventKind = "change" | "add" | "unlink" | "up";
@@ -62,8 +61,7 @@ export async function clearActivity(kv: KVNamespace, appDomain: string): Promise
 
 /**
  * Business-readable translation of a reported file path + event, for the
- * activity log. File-level only — no per-line diff enrichment (Darrin,
- * 2026-07-14: "we can show that in step 2").
+ * activity log. File-level only — no per-line diff enrichment.
  */
 export function describeActivity(file: string | undefined, event: ActivityEventKind): string {
   if (event === "up") return "Your store is running locally";

package/apps/storefront/src/lib/dev/apiBase.ts

@@ -3,12 +3,9 @@
  * click-to-source). Local `astro dev` serves these off dev-server-only plugins at
  * `/__tot/*` (dev-plugins/dev-file-browser.mjs, dev-write.mjs, dev-diff.mjs, ...) —
  * paths that don't exist in the deployed Cloudflare Worker. The hosted Worker instead
- * serves the SAME shape off `/api/dev/*` Astro API routes, landing incrementally
+ * serves the SAME shape off `/api/dev/*` Astro API routes
  * (cp-tree, cp-file, cp-write, cp-diff, cp-locate). One dev.astro UI, one resolver.
  *
- * See decision `architecture-environment-aware-cockpit`
- * (workstream tot-lime-cloud-dev-cockpit).
- *
  * `basePath` is the request's tenant prefix ("" host-routed, "/<tenant>" path-routed).
  * The HOSTED routes are tenant-scoped through the middleware's host/path resolution, so
  * a `/<tenant>/cockpit` render must call `/<tenant>/api/dev/*` for `locals.tenant` to be

package/apps/storefront/src/lib/dev/cockpit/ask.ts

@@ -0,0 +1,49 @@
+/**
+ * "Stuck? Ask" recovery affordance. A quiet FAB that opens a scoped Q&A
+ * for "why isn't the loop working" — NOT general AI editing. Static answers
+ * ship as markup; the two stateful answers (is it running? / save-vs-reload)
+ * update from the shared tot:loop-state signal + window.__totLoop (monitor.ts
+ * — no second poll). "Reconnect preview" reloads the page, re-establishing
+ * the HMR connection and re-reading loop state (recovers a stale client); a
+ * fully-down server is handled by the answer text (run tot start). Imported
+ * from a processed `<script>` in cockpit.astro (ADR 0013), rendered only when
+ * isLocalDevLoop.
+ */
+export function initAsk(): void {
+  const fab = document.getElementById("askFab");
+  const panel = document.getElementById("askPanel");
+  if (!fab || !panel) return;
+  const ansRunning = document.getElementById("ans-running");
+  const ansChange = document.getElementById("ans-change");
+  const restart = document.getElementById("restartBtn");
+
+  fab.addEventListener("click", (e) => { e.stopPropagation(); panel.classList.toggle("open"); });
+  document.addEventListener("click", (e) => {
+    if (!panel.contains(e.target as Node) && e.target !== fab && !fab.contains(e.target as Node)) panel.classList.remove("open");
+  });
+  if (restart) restart.addEventListener("click", () => { location.reload(); });
+
+  function rel(ts: number | string): string {
+    const d = Math.max(0, Math.round((Date.now() - Number(ts)) / 1000));
+    return d < 2 ? "just now" : d < 60 ? d + "s ago" : Math.floor(d / 60) + "m ago";
+  }
+  function update(s: any) {
+    if (!s) return;
+    if (ansRunning) {
+      ansRunning.textContent = (s.offline || !s.server)
+        ? "Your dev server isn't reachable right now — run tot start in your terminal, then reload this page."
+        : "Yes — your server is running" + (s.port ? " on port " + s.port : "") + ". This page is connected to it.";
+    }
+    if (ansChange) {
+      if (!s.lastSaveAt) {
+        ansChange.textContent = "No saves seen yet. Edit a watched file (like content/home.html) and save — it'll show up here.";
+      } else if ((s.lastReloadAt || 0) >= s.lastSaveAt) {
+        ansChange.textContent = "Working: your last save (" + rel(s.lastSaveAt) + ") triggered a reload (" + rel(s.lastReloadAt) + "). If the page didn't visibly change, make sure you edited the file the page renders from.";
+      } else {
+        ansChange.textContent = "Your save (" + rel(s.lastSaveAt) + ") hasn't been reflected by a reload yet — the preview may be stale. Try Reconnect preview below.";
+      }
+    }
+  }
+  window.addEventListener("tot:loop-state", (e: any) => { update(e.detail); });
+  if (window.__totLoop) update(window.__totLoop);
+}

package/apps/storefront/src/lib/dev/cockpit/clickToSource.ts

@@ -0,0 +1,71 @@
+/**
+ * C8 · Click-to-source capstone — the cockpit side. Runs the live-preview
+ * iframe (mini + full-screen dialog) and LISTENS for the framed picker's
+ * tot:locate postMessage. The picker (ai-widget-client.js, auto-injected into
+ * the same-origin preview) resolves a click to {path,line,col} via
+ * /__tot/locate, then — because it is framed — postMessages the result here
+ * instead of showing its own toast. We verify event.origin === our origin,
+ * then hand off to files.ts's window.__totOpenFileAt to open the source +
+ * drop the caret. Only content-region hits ever arrive (chrome/refused
+ * clicks stay silent in the frame), per decision
+ * click-to-source-anchors-at-content-region. Imported from a processed
+ * `<script>` in cockpit.astro (ADR 0013), rendered only when isLocalDevLoop.
+ * isDev and the hosted app domain are read from `document.body.dataset`.
+ */
+export function initClickToSource(): void {
+  const isDev = document.body.dataset.cockpitIsDev === "true";
+  const hostedAppDomain = document.body.dataset.cockpitAppDomain || "";
+  const dlg: any = document.getElementById("previewDialog");
+  const expandBtn = document.getElementById("previewExpand");
+  const closeBtn = document.getElementById("previewClose");
+  const dlgFrame: any = document.getElementById("previewDialogFrame");
+  const miniFrame: any = document.getElementById("previewFrame");
+  const urlEl = document.getElementById("previewUrl");
+
+  if (miniFrame) {
+    if (isDev) {
+      // Point the preview at the DEV tenant (TOT_DEV_TENANT), read from the server
+      // via /__tot/dev-loop-status — NOT the SSR appDomain (workerd can't see
+      // TOT_DEV_*). Same-origin, so the auto-injected picker can postMessage back.
+      fetch("/__tot/dev-loop-status")
+        .then((r) => r.json())
+        .then((s) => {
+          const tenant = s && s.tenant;
+          if (!tenant) return;
+          const src = "/" + tenant + "/";
+          miniFrame.src = src;
+          if (urlEl) urlEl.textContent = "localhost preview · " + tenant;
+        })
+        .catch(() => { /* dev server unreachable — preview stays blank */ });
+    } else if (hostedAppDomain) {
+      // Hosted: the SSR-resolved tenant IS the signed-in developer's own store
+      // (cp-env's capability gate already scoped it) — same-origin, so a cp-write
+      // save + this reload shows the developer's own draft overlay via the
+      // middleware's tot_dev_draft cookie check.
+      miniFrame.src = "/" + hostedAppDomain + "/";
+      if (urlEl) urlEl.textContent = "your store · " + hostedAppDomain;
+    }
+  }
+
+  if (expandBtn && dlg) {
+    expandBtn.addEventListener("click", () => {
+      if (dlgFrame && !dlgFrame.getAttribute("src") && miniFrame) dlgFrame.src = miniFrame.getAttribute("src") || miniFrame.src;
+      if (typeof dlg.showModal === "function") dlg.showModal(); else dlg.setAttribute("open", "");
+    });
+  }
+  if (closeBtn && dlg) closeBtn.addEventListener("click", () => { dlg.close ? dlg.close() : dlg.removeAttribute("open"); });
+  if (dlg) dlg.addEventListener("click", (e: MouseEvent) => { if (e.target === dlg) { dlg.close ? dlg.close() : dlg.removeAttribute("open"); } });
+
+  // The one privileged inbound message: a source location from OUR OWN origin's
+  // framed preview. Reject any other origin, shape, or type outright.
+  window.addEventListener("message", (e) => {
+    if (e.origin !== window.location.origin) return;
+    const d: any = e.data;
+    if (!d || d.type !== "tot:locate" || typeof d.path !== "string") return;
+    if (typeof (window as any).__totOpenFileAt === "function") {
+      const opened = (window as any).__totOpenFileAt(d.path, d.line, d.col);
+      // If the preview was expanded full-screen, close it so the editor + caret are visible.
+      if (opened && dlg && dlg.open) { dlg.close ? dlg.close() : dlg.removeAttribute("open"); }
+    }
+  });
+}