instar 1.3.48 → 1.3.49

package/dist/feedback-factory/dryrun/HttpParitySource.d.ts

@@ -0,0 +1,82 @@
+/**
+ * HttpParitySource.ts — the live Phase-1/3 ParitySource adapter.
+ *
+ * Portal exposes `GET /api/instar/read` (Dawn, committed at d65136b3b6) as the
+ * read-only seam — the architectural pivot from raw Postgres after Prisma Data
+ * Platform refused to mint a database role (it forbids CREATE ROLE / GRANT). API
+ * level is actually a cleaner seam than direct DB access: the dry-run tests
+ * against the same contract Phase 2 (write/update APIs) will use, with no
+ * Prisma-admin dependency, and the architectural levels line up (Portal's HTTP
+ * surface ↔ Instar's {@link ParitySource} interface).
+ *
+ * This adapter implements ParitySource via that endpoint. The runner's seam,
+ * comparator, invariants, and JSONL audit trail are unchanged — only the read
+ * adapter swaps. Reads are PRE-FETCHED in {@link prepare}: the dry-run captures
+ * one snapshot of Portal's clusters at a moment in time, then compares against
+ * that frozen view. This makes the sync `readPortalClusters()` contract trivially
+ * satisfiable and stabilises the comparison against in-flight Portal writes
+ * (Portal remains the sole writer; we just look at one consistent slice).
+ *
+ * The endpoint is paginated (server-side cap: 1000 rows per request). The
+ * pagination is keyed off the feedback table — clusters/dispatches accompany each
+ * page and may repeat — so cluster collection deduplicates by clusterId across
+ * pages and stops when a page returns fewer feedback rows than the requested
+ * limit (the documented "no more pages" signal) OR after a hard safety cap.
+ *
+ * Field naming is intentionally tolerant: cluster rows may arrive as camelCase
+ * (Prisma default) or snake_case (raw SQL projection). The mapper accepts both.
+ */
+import type { ParitySource } from './dryRunCompare.js';
+import type { PortalCluster } from '../processor/parity.js';
+/** Minimal fetch shape the adapter needs (lets tests pass a stub). */
+export type FetchLike = (input: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export interface HttpParitySourceConfig {
+    /** Portal base URL, e.g. `https://portal.bot-me.ai`. */
+    baseUrl: string;
+    /** Bearer token with `instar:read` scope. */
+    token: string;
+    /** Page size sent as `?limit=`. Default 1000 (server max per Dawn's contract). */
+    pageSize?: number;
+    /** Safety cap on pagination loops. Default 200 pages (= 200k feedback rows). */
+    maxPages?: number;
+    /** Optional `?status=` filter passed through to the endpoint. */
+    status?: string;
+    /** Injectable fetch (for tests). Defaults to global `fetch`. */
+    fetchImpl?: FetchLike;
+    /** Optional path override (defaults to `/api/instar/read`). */
+    readPath?: string;
+}
+/** Error thrown when Portal returns non-OK. The status code is preserved for callers. */
+export declare class HttpParitySourceError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Live ParitySource backed by Portal's `/api/instar/read` endpoint. Construct
+ * with the base URL + read-scope token, then `await source.prepare()` once
+ * before passing to {@link runDryRunCompare}. The pre-fetch captures a single
+ * consistent snapshot of Portal's clusters; the runner reads it synchronously.
+ */
+export declare class HttpParitySource implements ParitySource {
+    private readonly config;
+    private snapshot;
+    private readonly pageSize;
+    private readonly maxPages;
+    private readonly fetch;
+    private readonly readPath;
+    constructor(config: HttpParitySourceConfig);
+    /** Pre-fetch and cache the cluster snapshot. Idempotent: re-calling re-fetches. */
+    prepare(): Promise<void>;
+    /** Sync ParitySource read — returns the snapshot captured by {@link prepare}. */
+    readPortalClusters(): PortalCluster[];
+}
+//# sourceMappingURL=HttpParitySource.d.ts.map

package/dist/feedback-factory/dryrun/HttpParitySource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpParitySource.d.ts","sourceRoot":"","sources":["../../../src/feedback-factory/dryrun/HttpParitySource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAAK,OAAO,CAAC;IACpH,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAiBD,yFAAyF;AACzF,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAgCD;;;;;GAKG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IAOvC,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEL,MAAM,EAAE,sBAAsB;IAU3D,mFAAmF;IAC7E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAqC9B,iFAAiF;IACjF,kBAAkB,IAAI,aAAa,EAAE;CAMtC"}

package/dist/feedback-factory/dryrun/HttpParitySource.js

@@ -0,0 +1,138 @@
+/**
+ * HttpParitySource.ts — the live Phase-1/3 ParitySource adapter.
+ *
+ * Portal exposes `GET /api/instar/read` (Dawn, committed at d65136b3b6) as the
+ * read-only seam — the architectural pivot from raw Postgres after Prisma Data
+ * Platform refused to mint a database role (it forbids CREATE ROLE / GRANT). API
+ * level is actually a cleaner seam than direct DB access: the dry-run tests
+ * against the same contract Phase 2 (write/update APIs) will use, with no
+ * Prisma-admin dependency, and the architectural levels line up (Portal's HTTP
+ * surface ↔ Instar's {@link ParitySource} interface).
+ *
+ * This adapter implements ParitySource via that endpoint. The runner's seam,
+ * comparator, invariants, and JSONL audit trail are unchanged — only the read
+ * adapter swaps. Reads are PRE-FETCHED in {@link prepare}: the dry-run captures
+ * one snapshot of Portal's clusters at a moment in time, then compares against
+ * that frozen view. This makes the sync `readPortalClusters()` contract trivially
+ * satisfiable and stabilises the comparison against in-flight Portal writes
+ * (Portal remains the sole writer; we just look at one consistent slice).
+ *
+ * The endpoint is paginated (server-side cap: 1000 rows per request). The
+ * pagination is keyed off the feedback table — clusters/dispatches accompany each
+ * page and may repeat — so cluster collection deduplicates by clusterId across
+ * pages and stops when a page returns fewer feedback rows than the requested
+ * limit (the documented "no more pages" signal) OR after a hard safety cap.
+ *
+ * Field naming is intentionally tolerant: cluster rows may arrive as camelCase
+ * (Prisma default) or snake_case (raw SQL projection). The mapper accepts both.
+ */
+/** Error thrown when Portal returns non-OK. The status code is preserved for callers. */
+export class HttpParitySourceError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = 'HttpParitySourceError';
+        this.status = status;
+    }
+}
+/**
+ * Coerce one raw cluster row into the {@link PortalCluster} shape. Accepts both
+ * camelCase and snake_case keys; missing optional fields stay undefined. Throws
+ * only when the required keys (clusterId, type, title, fingerprint) cannot be
+ * resolved — a row that opaque is a contract violation we want to surface.
+ */
+function coerceCluster(row) {
+    if (!row || typeof row !== 'object') {
+        throw new HttpParitySourceError(502, 'cluster row is not an object');
+    }
+    const r = row;
+    const pick = (...keys) => {
+        for (const k of keys)
+            if (r[k] !== undefined && r[k] !== null)
+                return r[k];
+        return undefined;
+    };
+    const clusterId = pick('clusterId', 'cluster_id', 'id');
+    const type = pick('type');
+    const title = pick('title');
+    const fingerprint = pick('fingerprint') ?? '';
+    if (typeof clusterId !== 'string' || typeof type !== 'string' || typeof title !== 'string') {
+        throw new HttpParitySourceError(502, `cluster row missing required fields (clusterId/type/title)`);
+    }
+    const out = { clusterId, type, title, fingerprint: String(fingerprint) };
+    const status = pick('status');
+    if (typeof status === 'string')
+        out.status = status;
+    const rc = pick('recurrenceCount', 'recurrence_count');
+    if (typeof rc === 'number')
+        out.recurrenceCount = rc;
+    return out;
+}
+/**
+ * Live ParitySource backed by Portal's `/api/instar/read` endpoint. Construct
+ * with the base URL + read-scope token, then `await source.prepare()` once
+ * before passing to {@link runDryRunCompare}. The pre-fetch captures a single
+ * consistent snapshot of Portal's clusters; the runner reads it synchronously.
+ */
+export class HttpParitySource {
+    config;
+    snapshot = null;
+    pageSize;
+    maxPages;
+    fetch;
+    readPath;
+    constructor(config) {
+        this.config = config;
+        this.pageSize = config.pageSize ?? 1000;
+        this.maxPages = config.maxPages ?? 200;
+        this.fetch = config.fetchImpl ?? globalThis.fetch;
+        this.readPath = config.readPath ?? '/api/instar/read';
+        if (!this.fetch) {
+            throw new HttpParitySourceError(500, 'no fetch available — pass fetchImpl or run on a runtime with global fetch');
+        }
+    }
+    /** Pre-fetch and cache the cluster snapshot. Idempotent: re-calling re-fetches. */
+    async prepare() {
+        const byId = new Map();
+        const base = this.config.baseUrl.replace(/\/+$/, '');
+        const authHeader = `Bearer ${this.config.token}`;
+        for (let page = 0; page < this.maxPages; page++) {
+            const offset = page * this.pageSize;
+            const qs = new URLSearchParams({ limit: String(this.pageSize), offset: String(offset) });
+            if (this.config.status)
+                qs.set('status', this.config.status);
+            const url = `${base}${this.readPath}?${qs.toString()}`;
+            const res = await this.fetch(url, { headers: { Authorization: authHeader, Accept: 'application/json' } });
+            if (!res.ok) {
+                let detail = '';
+                try {
+                    detail = (await res.text()).slice(0, 200);
+                }
+                catch { /* ignore */ }
+                throw new HttpParitySourceError(res.status, `Portal /api/instar/read failed (page ${page}, status ${res.status} ${res.statusText}): ${detail}`);
+            }
+            const envelope = (await res.json());
+            const rawClusters = envelope?.data?.clusters ?? [];
+            for (const raw of rawClusters) {
+                const c = coerceCluster(raw);
+                if (!byId.has(c.clusterId))
+                    byId.set(c.clusterId, c);
+            }
+            // Pagination stop signal: returned_count < pageSize means the feedback table
+            // is exhausted (clusters/dispatches per Dawn's contract accompany the feedback
+            // pages and stabilise quickly via the byId dedup above).
+            const returned = envelope?.meta?.returned_count ?? rawClusters.length;
+            if (returned < this.pageSize)
+                break;
+        }
+        this.snapshot = [...byId.values()];
+    }
+    /** Sync ParitySource read — returns the snapshot captured by {@link prepare}. */
+    readPortalClusters() {
+        if (this.snapshot === null) {
+            throw new HttpParitySourceError(500, 'HttpParitySource.prepare() must be awaited before readPortalClusters()');
+        }
+        return this.snapshot.map((c) => ({ ...c }));
+    }
+}
+//# sourceMappingURL=HttpParitySource.js.map

package/dist/feedback-factory/dryrun/HttpParitySource.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.48",
+  "version": "1.3.49",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-05-28T03:46:09.134Z",
-  "instarVersion": "1.3.48",
+  "generatedAt": "2026-05-28T03:52:42.963Z",
+  "instarVersion": "1.3.49",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.49.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+Next increment of the **Feedback Factory Migration** (Dawn → Echo; spec `docs/specs/feedback-factory-migration.md`, approved). Ships the **live Portal adapter** behind the dry-run/compare seam after a clean architectural pivot from Dawn (committed Portal-side at `d65136b3b6`): Prisma Data Platform forbids `CREATE ROLE`/`GRANT` for any account, so a read-only Postgres role can't be minted. Dawn replaced direct DB access with a Portal-internal endpoint `GET /api/instar/read` — Bearer-token-authed (`instar:read` scope), max 1000 rows per request, returns the same three tables (feedback, clusters, dispatches) with paging metadata.
+
+New module:
+
+- **`src/feedback-factory/dryrun/HttpParitySource.ts`** — implements the existing `ParitySource` interface via that endpoint. Async `prepare()` pre-fetches a consistent snapshot (walking pages, deduping clusters by `clusterId`, stopping when `returned_count < limit`). Sync `readPortalClusters()` returns the snapshot. The runner's seam, the parity comparator, the three order-independent invariants, and the JSONL audit trail are all unchanged — only the read adapter swaps.
+
+Still internal — not yet wired into any route or job. Live verification waits on the `instar:read` token landing via Secret Drop.
+
+## What to Tell Your User
+
+- Dawn hit a database-platform limitation (Prisma Cloud refuses to mint a read-only user) and pivoted to an internal HTTP endpoint instead. It's actually a cleaner seam — my dry-run tests against the same contract her Phase-2 work will use, with no Prisma-admin dependency.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| HTTP-backed live ParitySource for Phase-1/3 dry-run | Internal `src/feedback-factory/dryrun/HttpParitySource.ts` — `await new HttpParitySource({baseUrl,token}).prepare()`, then pass to `runDryRunCompare` |
+
+## Evidence
+
+- **10 new unit tests**, all green; full feedback-factory unit dir green; `tsc --noEmit` clean.
+- **Both-sides-of-boundary**: Bearer auth + field mapping (camelCase AND snake_case tolerance), single-page snapshot + multi-page pagination with `clusterId`-dedup + `returned_count < pageSize` stop signal, `maxPages` safety cap, error-status preservation, malformed-row rejection (no silent skip of contract violations), prepare-before-read invariant, defensive-copy snapshot.
+- **Faithful to the existing seam**: `HttpParitySource` is purely additive — implements the same `ParitySource` interface as `InMemoryParitySource`, so the runner / comparator / invariants / cutover gate are byte-identical for in-memory tests and the live Portal path.
+
+Side-effects: `upgrades/side-effects/feedback-factory-http-source.md`.

package/upgrades/side-effects/feedback-factory-http-source.md

@@ -0,0 +1,99 @@
+# Side-effects review — feedback-factory HttpParitySource adapter
+
+Spec: `docs/specs/feedback-factory-migration.md` (converged v2, approved 2026-05-26).
+Increment: the live Portal `/api/instar/read` adapter implementing the existing
+`ParitySource` seam. Single new src module + its unit test; zero edits to existing
+code.
+
+## What this ships
+
+The HTTP adapter behind the dry-run/compare seam after Dawn's architectural pivot
+(committed Portal-side at `d65136b3b6`): Prisma Data Platform forbids `CREATE ROLE`/
+`GRANT`/`REVOKE` for any account including superusers, so a read-only Postgres role
+couldn't be minted. Dawn replaced direct DB access with a Portal-internal endpoint
+`GET /api/instar/read` (max 1000 rows/request, Bearer-token-authed,
+`instar:read` scope, JSON envelope with `data.{feedback,clusters,dispatches}` +
+`meta.{total_feedback_rows,returned_count,query_time_ms,timestamp}`).
+
+`HttpParitySource` implements `ParitySource` by pre-fetching that snapshot via an
+async `prepare()` and serving it through the existing sync `readPortalClusters()`
+read. The runner's seam, comparator (parity.ts), invariants, audit trail
+(JSONL), and `divergent === true` cutover gate are unchanged — only the read
+adapter swaps. This is exactly what the dependency-injection seam was for.
+
+## Over-block / under-block
+
+- **Errors**: any non-OK Portal response throws `HttpParitySourceError` with the
+  preserved status code. No silent partial snapshots — a 401/403/5xx surfaces
+  immediately and halts the prepare(). This is the right direction (false
+  block is recoverable; a silent partial snapshot would produce a phantom
+  "divergent" verdict that blocks Phase 4 cutover for the wrong reason).
+- **Malformed cluster rows**: a row missing required fields (`clusterId` / `type`
+  / `title`) throws, NOT silently skipped. A contract violation from Portal is
+  exactly the kind of thing we need to see, not hide.
+- **Field naming tolerance**: the mapper accepts both camelCase (Prisma default)
+  and snake_case (raw SQL projection) — chosen because Dawn's endpoint contract
+  doesn't pin the projection style and over-strictness here would cause
+  needless live-rollout friction.
+- **Snapshot freshness**: `prepare()` is idempotent — re-calling re-fetches.
+  Callers that want a stable snapshot for one dry-run pass simply call it once;
+  callers that want a fresh snapshot per pass call it per pass. Neither path is
+  blocked.
+- **`readPortalClusters()` before `prepare()`**: throws (no silent empty array).
+  An empty snapshot would also produce a phantom "divergent: false" verdict that
+  would mis-gate cutover.
+
+## Level-of-abstraction fit
+
+- The adapter lives in `dryrun/` next to `dryRunCompare.ts` because it is the
+  composition's read-source, not a pure piece of the processor logic
+  (`processor/` stays pure / decision-only).
+- It implements the existing `ParitySource` interface verbatim — the seam was
+  designed for exactly this swap. The runner doesn't know whether it's reading
+  from `InMemoryParitySource` or `HttpParitySource`; that's the test/live
+  symmetry the migration spec called for.
+- `fetch` is injected via `fetchImpl` so unit tests can stub it. The default
+  uses the runtime's global `fetch` (Node ≥18 / modern fetch).
+
+## Signal-vs-authority compliance
+
+Still signal-only. The adapter produces data; the runner produces a verdict; no
+authority to act flows from this code. Portal stays sole writer (the
+read-only API surface does not expose mutation). The cutover authority remains
+where the spec puts it: Dawn's line-by-line review + Justin's go/no-go.
+
+## Interactions
+
+- **Portal `/api/instar/read`**: the only external surface this adapter touches.
+  Read-only by Dawn's design (no PUT/POST/DELETE in the endpoint contract). The
+  Bearer token (`instar:read` scope) sits in the adapter's config — never logged,
+  never persisted by the adapter, owned by the caller. Token delivery happens
+  out of band via Secret Drop (in-memory only, never on disk, never in chat
+  history).
+- **`ParitySource` interface, `runDryRunCompare`, `parity.ts`**: unchanged. No
+  edits to existing feedback-factory code — additive only.
+- **No config, hook, route, template, or migration surface is touched.** No
+  Migration Parity / Agent Awareness obligation triggered.
+- **Pagination contract**: keyed off the feedback table (`returned_count <
+  pageSize` = exhausted). Clusters/dispatches per Dawn's contract accompany
+  each page; the adapter dedupes clusters by `clusterId` across pages, so
+  repeated clusters across pages cost only the network round-trip, not
+  correctness. Safety cap at `maxPages` (default 200 = 200k feedback rows)
+  prevents infinite-loop pathology if Portal returned the wrong meta.
+
+## Rollback cost
+
+Trivial. One new `src/feedback-factory/dryrun/HttpParitySource.ts` plus its test.
+Nothing imports it from production paths yet. Reverting removes the adapter
+without any downstream impact.
+
+## Deferrals
+
+- **Live verification** waits on the `instar:read` token landing via the open
+  Secret Drop. The adapter + 10 unit tests fully prove the read shape, mapping,
+  pagination, error path, and prepare-invariant against a stubbed `fetch`; the
+  live token only exercises the actual Portal endpoint. <!-- tracked: topic-12476 -->
+- **Cursor-based pagination** (a Last-Modified-style cursor instead of offset)
+  is not used: Dawn's documented contract is offset/limit. If she adds a cursor
+  later, the adapter takes one config field and a small page-loop tweak. The
+  current offset-with-dedup is correct under offset semantics. <!-- tracked: topic-12476 -->