@productbrain/cli 0.1.0-beta.9 → 0.1.0-beta.9000

package/dist/lib/judgeWait.d.ts

@@ -0,0 +1,50 @@
+/**
+ * An accept waits for the judge already in flight, then commits once (DEC-1935; TASK-612; WP-801).
+ *
+ * The kernel mutation `quality.evaluateHeuristicAndSchedule` with context 'commit' decides whether
+ * the accept needs a fresh judgment or reuses the verdict already settled (passed or failing) or in flight, and says
+ * `judgeInFlight` when an AI judge run is going. This module is the one ordering both connectors
+ * run before `chain.commitEntry`: evaluate, then, when a judge is in flight, poll the latest
+ * verdict until its llmStatus leaves 'pending' or the bound runs out (a reused verdict is read once). The gate inside commitEntry
+ * stays the only decider of accept or refuse. Zero imports: the copies generator mirrors this
+ * file into packages/cli and packages/mcp-server (scripts/generate-mcp-embedded-copies.mjs).
+ */
+/** The background AI judge's per-call timeout (convex/intelligence/qualityCoaching.ts uses this value). */
+export declare const JUDGE_TIMEOUT_MS = 30000;
+/**
+ * The most sequential judge calls one background run makes before it stores the verdict: the
+ * checklist, then the Roger Martin probe for a rubric that names it (strategy, kernel/quality/rubrics.ts).
+ */
+export declare const JUDGE_CALLS_PER_RUN = 2;
+/** How long an accept waits: every call of one run at its timeout, plus 5 s for the scheduler. */
+export declare const JUDGE_WAIT_BOUND_MS: number;
+export type JudgeEvaluation = {
+    judgeInFlight?: boolean;
+    reused?: boolean;
+} | null | undefined;
+export type LatestVerdictRead = {
+    verdict: {
+        llmStatus?: string;
+    } | null;
+} | null | undefined;
+export interface JudgeWaitResult<E, L> {
+    /** The evaluate call's reply (null when it threw: the gate still decides). */
+    evaluation: E | null;
+    /** The stored verdict as last read, settled unless the bound ran out (null when nothing was read). */
+    latest: L | null;
+    /** Milliseconds spent waiting for the in-flight judge; 0 when nothing was in flight. */
+    waitedMs: number;
+    /** True when the judge was in flight and its verdict landed within the bound. */
+    judged: boolean;
+}
+export declare function settleVerdictBeforeAccept<E extends JudgeEvaluation, L extends LatestVerdictRead>(evaluate: () => Promise<E>, readLatest: () => Promise<L>, opts?: {
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    boundMs?: number;
+}): Promise<JudgeWaitResult<E, L>>;
+/** The one line an accept that waited for the judge prints: "Judged in 14 s, accepted." */
+export declare function judgedAcceptedLine(wait: {
+    waitedMs: number;
+    judged: boolean;
+} | null): string | null;
+//# sourceMappingURL=judgeWait.d.ts.map

package/dist/lib/judgeWait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgeWait.d.ts","sourceRoot":"","sources":["../../src/lib/judgeWait.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,2GAA2G;AAC3G,eAAO,MAAM,gBAAgB,QAAS,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,kGAAkG;AAClG,eAAO,MAAM,mBAAmB,QAAiD,CAAC;AAIlF,MAAM,MAAM,eAAe,GAAG;IAAE,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAC/F,MAAM,MAAM,iBAAiB,GAAG;IAAE,OAAO,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAE9F,MAAM,WAAW,eAAe,CAAC,CAAC,EAAE,CAAC;IACpC,8EAA8E;IAC9E,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC;IACrB,sGAAsG;IACtG,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IACjB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,MAAM,EAAE,OAAO,CAAC;CAChB;AAED,wBAAsB,yBAAyB,CAAC,CAAC,SAAS,eAAe,EAAE,CAAC,SAAS,iBAAiB,EACrG,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC1B,UAAU,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC5B,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACxF,OAAO,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CA2BhC;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAGpG"}

package/dist/lib/judgeWait.js

@@ -0,0 +1,64 @@
+// GENERATED by scripts/generate-mcp-embedded-copies.mjs from kernel/quality/judgeWait.ts.
+// DO NOT EDIT. Run `npm run mcp:embedded-copies` to regenerate.
+// Local runtime copy for the isolated connector build.
+/**
+ * An accept waits for the judge already in flight, then commits once (DEC-1935; TASK-612; WP-801).
+ *
+ * The kernel mutation `quality.evaluateHeuristicAndSchedule` with context 'commit' decides whether
+ * the accept needs a fresh judgment or reuses the verdict already settled (passed or failing) or in flight, and says
+ * `judgeInFlight` when an AI judge run is going. This module is the one ordering both connectors
+ * run before `chain.commitEntry`: evaluate, then, when a judge is in flight, poll the latest
+ * verdict until its llmStatus leaves 'pending' or the bound runs out (a reused verdict is read once). The gate inside commitEntry
+ * stays the only decider of accept or refuse. Zero imports: the copies generator mirrors this
+ * file into packages/cli and packages/mcp-server (scripts/generate-mcp-embedded-copies.mjs).
+ */
+/** The background AI judge's per-call timeout (convex/intelligence/qualityCoaching.ts uses this value). */
+export const JUDGE_TIMEOUT_MS = 30_000;
+/**
+ * The most sequential judge calls one background run makes before it stores the verdict: the
+ * checklist, then the Roger Martin probe for a rubric that names it (strategy, kernel/quality/rubrics.ts).
+ */
+export const JUDGE_CALLS_PER_RUN = 2;
+/** How long an accept waits: every call of one run at its timeout, plus 5 s for the scheduler. */
+export const JUDGE_WAIT_BOUND_MS = JUDGE_CALLS_PER_RUN * JUDGE_TIMEOUT_MS + 5_000;
+const POLL_MS = 1_000;
+export async function settleVerdictBeforeAccept(evaluate, readLatest, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const bound = opts.boundMs ?? JUDGE_WAIT_BOUND_MS;
+    let evaluation = null;
+    try {
+        evaluation = await evaluate();
+    }
+    catch {
+        // Advisory: the gate inside commitEntry reads the stored verdict and decides alone.
+        return { evaluation: null, latest: null, waitedMs: 0, judged: false };
+    }
+    // A fresh evaluation with no judge run is the whole verdict; a reused one is read back as stored.
+    if (!evaluation?.judgeInFlight && !evaluation?.reused)
+        return { evaluation, latest: null, waitedMs: 0, judged: false };
+    const inFlight = evaluation.judgeInFlight === true;
+    const start = now();
+    let latest = null;
+    for (;;) {
+        try {
+            latest = await readLatest();
+        }
+        catch {
+            // A failed read ends the wait; the gate refuses honestly if the judge has not landed.
+            return { evaluation, latest, waitedMs: now() - start, judged: false };
+        }
+        if (latest?.verdict?.llmStatus !== 'pending')
+            return { evaluation, latest, waitedMs: now() - start, judged: inFlight };
+        if (now() - start >= bound)
+            return { evaluation, latest, waitedMs: now() - start, judged: false };
+        await sleep(POLL_MS);
+    }
+}
+/** The one line an accept that waited for the judge prints: "Judged in 14 s, accepted." */
+export function judgedAcceptedLine(wait) {
+    if (!wait?.judged)
+        return null;
+    return `Judged in ${Math.max(1, Math.round(wait.waitedMs / 1000))} s, accepted.`;
+}
+//# sourceMappingURL=judgeWait.js.map

package/dist/lib/judgeWait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgeWait.js","sourceRoot":"","sources":["../../src/lib/judgeWait.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,gEAAgE;AAChE,uDAAuD;AAEvD;;;;;;;;;;GAUG;AAEH,2GAA2G;AAC3G,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEvC;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAErC,kGAAkG;AAClG,MAAM,CAAC,MAAM,mBAAmB,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,KAAK,CAAC;AAElF,MAAM,OAAO,GAAG,KAAK,CAAC;AAgBtB,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC9C,QAA0B,EAC1B,UAA4B,EAC5B,OAAwF,EAAE;IAE1F,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1F,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,IAAI,mBAAmB,CAAC;IAClD,IAAI,UAAU,GAAa,IAAI,CAAC;IAChC,IAAI,CAAC;QACJ,UAAU,GAAG,MAAM,QAAQ,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACR,oFAAoF;QACpF,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACvE,CAAC;IACD,kGAAkG;IAClG,IAAI,CAAC,UAAU,EAAE,aAAa,IAAI,CAAC,UAAU,EAAE,MAAM;QAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IACvH,MAAM,QAAQ,GAAG,UAAU,CAAC,aAAa,KAAK,IAAI,CAAC;IACnD,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC;IACpB,IAAI,MAAM,GAAa,IAAI,CAAC;IAC5B,SAAS,CAAC;QACT,IAAI,CAAC;YACJ,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACR,sFAAsF;YACtF,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QACvE,CAAC;QACD,IAAI,MAAM,EAAE,OAAO,EAAE,SAAS,KAAK,SAAS;YAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;QACvH,IAAI,GAAG,EAAE,GAAG,KAAK,IAAI,KAAK;YAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAClG,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;AACF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,IAAkD;IACpF,IAAI,CAAC,IAAI,EAAE,MAAM;QAAE,OAAO,IAAI,CAAC;IAC/B,OAAO,aAAa,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,eAAe,CAAC;AAClF,CAAC"}

package/dist/lib/kernelEnvelope.d.ts

@@ -0,0 +1,42 @@
+/** Structured field-level detail from a VALIDATION_FAILED response. */
+export interface ValidationErrorDetail {
+    fieldKey: string;
+    fieldLabel: string;
+    invalidValue: unknown;
+    validOptions?: string[];
+    errorType: 'type_mismatch' | 'invalid_option' | 'required';
+    message: string;
+}
+/** An authority refusal's guidance as the gateway sends it in `details` (convex/lib/gatewayResponses.ts authRefusalDetails). */
+export interface AuthorityRefusalDetail {
+    requiredAction?: string;
+    routeTarget?: {
+        teamEntryId: string;
+        roleEntryId: string;
+        personIds: string[];
+    };
+}
+/** Reads the authority-refusal detail off an envelope's `details`, or undefined when it carries none (validation details never have these keys). */
+export declare function authorityFromDetails(details: readonly unknown[] | undefined): AuthorityRefusalDetail | undefined;
+export type KernelEnvelope<T> = {
+    ok?: boolean;
+    data?: T;
+    summary?: string;
+    error?: string;
+    message?: string;
+    code?: string;
+    details?: ValidationErrorDetail[];
+    /** Present only when code === 'rate-limited' (TEN-656) — seconds until the caller may retry. */
+    retryAfterSeconds?: number;
+    _meta?: {
+        durationMs?: number;
+        truncated?: boolean;
+    };
+};
+export declare function recordLatestFromResponse(res: Response): void;
+export declare function parseKernelEnvelope<T>(res: Response, route?: {
+    fn: string;
+    budgetMs: number;
+    args?: unknown;
+}): Promise<KernelEnvelope<T>>;
+//# sourceMappingURL=kernelEnvelope.d.ts.map

package/dist/lib/kernelEnvelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernelEnvelope.d.ts","sourceRoot":"","sources":["../../src/lib/kernelEnvelope.ts"],"names":[],"mappings":"AAeA,uEAAuE;AACvE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,eAAe,GAAG,gBAAgB,GAAG,UAAU,CAAC;IAC3D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gIAAgI;AAChI,MAAM,WAAW,sBAAsB;IACrC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACjF;AAED,oJAAoJ;AACpJ,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,GAAG,SAAS,GAAG,sBAAsB,GAAG,SAAS,CAWhH;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI;IAC9B,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,qBAAqB,EAAE,CAAC;IAClC,gGAAgG;IAChG,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAK3B,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACtD,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAE5D;AAED,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,GAAG,EAAE,QAAQ,EAIb,KAAK,CAAC,EAAE;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GACvD,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CA2B5B"}

package/dist/lib/kernelEnvelope.js

@@ -0,0 +1,67 @@
+/**
+ * The gateway envelope — its shape, and how to read one off a `Response`.
+ *
+ * Split out of client.ts in the WP-575 review round (STD-2 / DEC-1504: client.ts crossed the
+ * 500-LOC budget). The seam is a real one, not a line-count dodge: client.ts's job is to MAKE
+ * gateway calls — decide the budget, carry auth, retry a 429, drive the spinner. Deciding what
+ * the bytes coming back MEAN, and what a failure to read them means, is a different job. It is
+ * the same split the mcp-server connector already has between its `client.ts` and
+ * `gatewaySeam.ts`.
+ *
+ * The load-bearing part is `parseKernelEnvelope`'s body-phase abort branch — see its comment.
+ */
+import { recordServerLatest } from './update-check.js';
+import { gatewayTimeoutError, isTimeoutAbort } from './gatewayTimeout.js';
+/** Reads the authority-refusal detail off an envelope's `details`, or undefined when it carries none (validation details never have these keys). */
+export function authorityFromDetails(details) {
+    for (const d of details ?? []) {
+        if (!d || typeof d !== 'object')
+            continue;
+        const { requiredAction, routeTarget } = d;
+        if (typeof requiredAction !== 'string' && (typeof routeTarget !== 'object' || routeTarget === null))
+            continue;
+        return {
+            ...(typeof requiredAction === 'string' ? { requiredAction } : {}),
+            ...(typeof routeTarget === 'object' && routeTarget !== null ? { routeTarget: routeTarget } : {}),
+        };
+    }
+    return undefined;
+}
+export function recordLatestFromResponse(res) {
+    recordServerLatest(res.headers?.get?.('pb-latest-cli-version') ?? null);
+}
+export async function parseKernelEnvelope(res, 
+// WP-575 (PR #533 review, Codex P1): the route this body belongs to, so a BODY-phase budget
+// abort can be classified as the timeout it is. Optional — `validateKey` runs its own
+// AbortController and its own catch, and is deliberately left on the lenient path below.
+route) {
+    recordLatestFromResponse(res);
+    try {
+        return (await res.json());
+    }
+    catch (err) {
+        // `fetch` resolves at HEADERS while the budget signal is still live, so a stalled BODY
+        // aborts HERE, not at the fetch — outside the caller's timeout-classification try. The
+        // old blanket `.catch(() => ({}))` swallowed that into an empty envelope, which a 200
+        // status then read as SUCCESS with `undefined` data: a timed-out write reported as
+        // completed. That is the precise false-outcome this work package exists to remove, and
+        // the sibling of the MCP-side fix already landed as `throwClassifiedGatewayFailure`
+        // (mcp-server/src/gatewaySeam.ts) — the CLI had the same hole in all three call variants.
+        //
+        // Gated on `res.ok` (PR #533 review round 5): a NON-OK status means the server already
+        // reached a verdict and said so — only its error BODY stalled. Classifying that as a budget
+        // timeout would replace a real status and code (a 429's `retryAfterSeconds`, a 4xx's
+        // validation code) with "may have completed anyway, search before retrying", about a call
+        // the server explicitly failed. Falling through to the empty envelope hands it to the
+        // `!res.ok` check every caller already runs on the next line — the behaviour non-OK
+        // responses have always had. The timeout classification is for the case that is genuinely
+        // all we know: a 2xx whose body never arrived.
+        if (route && res.ok && isTimeoutAbort(err))
+            throw gatewayTimeoutError(route.fn, route.budgetMs, route.args);
+        // Any OTHER parse failure keeps the pre-existing lenient behavior on purpose: a non-JSON
+        // or empty body is already handled by the ok/status checks every caller runs against the
+        // empty envelope, and narrowing that here would change unrelated error paths.
+        return {};
+    }
+}
+//# sourceMappingURL=kernelEnvelope.js.map

package/dist/lib/kernelEnvelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kernelEnvelope.js","sourceRoot":"","sources":["../../src/lib/kernelEnvelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAkB1E,oJAAoJ;AACpJ,MAAM,UAAU,oBAAoB,CAAC,OAAuC;IAC1E,KAAK,MAAM,CAAC,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;QAC9B,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,SAAS;QAC1C,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,GAAG,CAA4B,CAAC;QACrE,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,CAAC,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,IAAI,CAAC;YAAE,SAAS;QAC9G,OAAO;YACL,GAAG,CAAC,OAAO,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjE,GAAG,CAAC,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAoD,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1I,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAmBD,MAAM,UAAU,wBAAwB,CAAC,GAAa;IACpD,kBAAkB,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,uBAAuB,CAAC,IAAI,IAAI,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAa;AACb,4FAA4F;AAC5F,sFAAsF;AACtF,yFAAyF;AACzF,KAAwD;IAExD,wBAAwB,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAsB,CAAC;IACjD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,uFAAuF;QACvF,uFAAuF;QACvF,sFAAsF;QACtF,mFAAmF;QACnF,uFAAuF;QACvF,oFAAoF;QACpF,0FAA0F;QAC1F,EAAE;QACF,uFAAuF;QACvF,4FAA4F;QAC5F,qFAAqF;QACrF,0FAA0F;QAC1F,sFAAsF;QACtF,oFAAoF;QACpF,0FAA0F;QAC1F,+CAA+C;QAC/C,IAAI,KAAK,IAAI,GAAG,CAAC,EAAE,IAAI,cAAc,CAAC,GAAG,CAAC;YAAE,MAAM,mBAAmB,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5G,yFAAyF;QACzF,yFAAyF;QACzF,8EAA8E;QAC9E,OAAO,EAAuB,CAAC;IACjC,CAAC;AACH,CAAC"}

package/dist/lib/legalRelationTypes.d.ts

@@ -0,0 +1,26 @@
+/** Filters a workspace-declared `valid_relation_types` array down to verbs `pb relate`'s
+ *  generic door can actually create toward the given target. `targetIsDomain` should be
+ *  `true` when the link target entry's canonicalKey is 'domain'; `sourceIsStrategy` should be
+ *  `true` when the entry being captured has canonicalKey 'strategy'. */
+export declare function filterCreatableRelationTypes(declared: unknown, targetIsDomain: boolean, sourceIsStrategy: boolean): string[];
+type TypeRow = {
+    data?: {
+        canonical_key?: unknown;
+        valid_relation_types?: unknown;
+        description?: unknown;
+        cardinality_rule?: unknown;
+    } | null;
+    status?: string;
+};
+/** Resolves the declared `valid_relation_types` for `canonicalKey` out of a semantic-types
+ *  listEntries result the SAME way loadTypeMap does (convex/chain/semanticTypes.ts:81-99):
+ *  trust-accepted AND parsable rows only, and when duplicate canonical_key rows exist (a
+ *  supported state — `canonical_key` is NOT DB-unique across rows, per semanticTypes.ts's own
+ *  loadTypeProvenance doc comment; semanticTypes.test.ts's `AND-reduces to false...` cases seed
+ *  exactly this active-duplicate shape) the LAST such match in listEntries' query order wins,
+ *  mirroring loadTypeMap's Map.set()-overwrite-per-match loop over the same by_collection-indexed
+ *  query — a malformed duplicate is skipped entirely rather than overwriting an earlier valid row
+ *  (bcRICo). Then filters to what `pb relate` can create. */
+export declare function resolveCreatableRelationTypes(typeRows: readonly TypeRow[] | null | undefined, canonicalKey: string, targetIsDomain: boolean): string[];
+export {};
+//# sourceMappingURL=legalRelationTypes.d.ts.map

package/dist/lib/legalRelationTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legalRelationTypes.d.ts","sourceRoot":"","sources":["../../src/lib/legalRelationTypes.ts"],"names":[],"mappings":"AAiDA;;;wEAGwE;AACxE,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,EAAE,OAAO,GAAG,MAAM,EAAE,CAS5H;AAED,KAAK,OAAO,GAAG;IACb,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7H,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAcF;;;;;;;;6DAQ6D;AAC7D,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,GAAG,SAAS,EAC/C,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,OAAO,GACtB,MAAM,EAAE,CASV"}

package/dist/lib/legalRelationTypes.js

@@ -0,0 +1,91 @@
+/**
+ * WP-688 S4 review round 5 (bdB5K, cQFZ_): `pb capture`'s --link-type refusal door
+ * (commands/capture.ts) lists an entry's declared legal relation verbs as a `pb relate`
+ * recovery hint. "Declared" (the workspace's own semantic-type row, `valid_relation_types`)
+ * is NOT the same set as "creatable via pb relate's generic door" — guardRelation
+ * (convex/lib/guards.ts) hard-refuses some declared verbs outright:
+ *   - replaces / do_not_confuse_with: always refused, routed to a different command
+ *     (guards.ts:309-322).
+ *   - Any verb outside the kernel ALLOWED_RELATION_TYPES set: refused regardless of what a
+ *     workspace's own type row declares (guards.ts:302-307) — registry reconciliation
+ *     deliberately preserves a customized `valid_relation_types` value even when it contains
+ *     a verb the kernel allowlist doesn't recognize (registryReconcile.test.ts:131-147), so
+ *     this is a supported persisted state, not malformed data.
+ *   - belongs_to / authority_domain TOWARD a domain-tagged target (target canonicalKey ===
+ *     'domain'): requires ratification metadata (stagingEntryId + source) `pb relate` cannot
+ *     supply (guards.ts:349-363).
+ *   - anchored_to FROM a non-strategy source: its entire meaning is strategy-scope-anchor
+ *     (WP-641 S2a) — predictStrategyAnchorViolation unconditionally rejects it whenever the
+ *     source canonicalKey isn't 'strategy' (singletonCardinality.ts:339-341), regardless of
+ *     target (round-5 finding bcRgRI).
+ * Centralized here so the filter isn't duplicated (or drifts) if another connector ever needs
+ * the same "legal AND creatable" list.
+ *
+ * WP-688 S4 review round 5 (bcQWqA): ALLOWED_RELATION_TYPES is read at RUNTIME (a filter, not a
+ * type check), so it cannot come from a bare `kernel/entries/relationTypes` value import —
+ * `kernel` is a devDependency-only, unpublished workspace package (present locally via monorepo
+ * linking, absent from the published `@productbrain/cli` npm package), so that import resolves
+ * here in dev/test but throws ERR_MODULE_NOT_FOUND for every real npm-installed `pb` command
+ * (index.ts statically imports capture.ts, which statically imports this file). Import the
+ * generated, CLI-owned copy instead — same pattern as sourceSurfaces.generated.ts (see
+ * scripts/generate-kernel-value-sets.mjs's header for the full rationale + retirement rule).
+ */
+import { ALLOWED_RELATION_TYPES as ALLOWED_RELATION_TYPES_LIST } from '../generated/relationTypes.generated.js';
+import { isTrustAccepted } from './statusCategories.js'; // TASK-587 (WP-779, TEN-4295): generated copy of the kernel helper
+const ALLOWED_RELATION_TYPES = new Set(ALLOWED_RELATION_TYPES_LIST);
+/** Verbs guardRelation refuses outright regardless of ALLOWED_RELATION_TYPES membership — each
+ *  routes to a different, specialized command instead of the generic relation door. */
+const DIRECT_DOOR_BLOCKED = new Set(['replaces', 'do_not_confuse_with']);
+/** Domain-tag verbs guardRelation only accepts via ratification metadata (guards.ts:349-363) —
+ *  `pb relate` cannot supply it, so never recommend these toward a domain-tagged target. */
+const DOMAIN_TAG_VERBS = new Set(['belongs_to', 'authority_domain']);
+/** anchored_to only exists as a strategy-scope-anchor verb (WP-641 S2a) — never legal from a
+ *  non-strategy source, regardless of target (bcRgRI). */
+const STRATEGY_ONLY_VERBS = new Set(['anchored_to']);
+/** Filters a workspace-declared `valid_relation_types` array down to verbs `pb relate`'s
+ *  generic door can actually create toward the given target. `targetIsDomain` should be
+ *  `true` when the link target entry's canonicalKey is 'domain'; `sourceIsStrategy` should be
+ *  `true` when the entry being captured has canonicalKey 'strategy'. */
+export function filterCreatableRelationTypes(declared, targetIsDomain, sourceIsStrategy) {
+    if (!Array.isArray(declared))
+        return [];
+    return declared.filter((t) => typeof t === 'string'
+        && !DIRECT_DOOR_BLOCKED.has(t)
+        && ALLOWED_RELATION_TYPES.has(t)
+        && !(targetIsDomain && DOMAIN_TAG_VERBS.has(t))
+        && !(!sourceIsStrategy && STRATEGY_ONLY_VERBS.has(t)));
+}
+/** Mirrors parseSemanticTypeDefData's validity rule (kernel/entries/semanticTypes.ts:65-77) —
+ *  loadTypeMap skips a malformed row (missing/non-string description, or a cardinality_rule
+ *  outside the 3-value enum) rather than letting it win, even when it's the LAST trust-accepted
+ *  duplicate (round-5 finding bcRICo). Inlined rather than imported: same devDependency-only/
+ *  unpublished-kernel constraint as ALLOWED_RELATION_TYPES above. */
+function isParsableSemanticTypeRow(data) {
+    return typeof data?.description === 'string'
+        && (data.cardinality_rule === 'singleton_per_workspace'
+            || data.cardinality_rule === 'singleton_per_scope'
+            || data.cardinality_rule === 'multiple');
+}
+/** Resolves the declared `valid_relation_types` for `canonicalKey` out of a semantic-types
+ *  listEntries result the SAME way loadTypeMap does (convex/chain/semanticTypes.ts:81-99):
+ *  trust-accepted AND parsable rows only, and when duplicate canonical_key rows exist (a
+ *  supported state — `canonical_key` is NOT DB-unique across rows, per semanticTypes.ts's own
+ *  loadTypeProvenance doc comment; semanticTypes.test.ts's `AND-reduces to false...` cases seed
+ *  exactly this active-duplicate shape) the LAST such match in listEntries' query order wins,
+ *  mirroring loadTypeMap's Map.set()-overwrite-per-match loop over the same by_collection-indexed
+ *  query — a malformed duplicate is skipped entirely rather than overwriting an earlier valid row
+ *  (bcRICo). Then filters to what `pb relate` can create. */
+export function resolveCreatableRelationTypes(typeRows, canonicalKey, targetIsDomain) {
+    let declared;
+    for (const row of typeRows ?? []) {
+        if (row.data?.canonical_key !== canonicalKey)
+            continue;
+        if (row.status === undefined || !isTrustAccepted(row.status))
+            continue;
+        if (!isParsableSemanticTypeRow(row.data))
+            continue;
+        declared = row.data?.valid_relation_types;
+    }
+    return filterCreatableRelationTypes(declared, targetIsDomain, canonicalKey === 'strategy');
+}
+//# sourceMappingURL=legalRelationTypes.js.map

package/dist/lib/legalRelationTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legalRelationTypes.js","sourceRoot":"","sources":["../../src/lib/legalRelationTypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,EAAE,sBAAsB,IAAI,2BAA2B,EAAE,MAAM,yCAAyC,CAAC;AAChH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC,CAAC,mEAAmE;AAE5H,MAAM,sBAAsB,GAAwB,IAAI,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAEzF;uFACuF;AACvF,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC,CAAC;AAE9F;4FAC4F;AAC5F,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAE1F;0DAC0D;AAC1D,MAAM,mBAAmB,GAAwB,IAAI,GAAG,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;AAE1E;;;wEAGwE;AACxE,MAAM,UAAU,4BAA4B,CAAC,QAAiB,EAAE,cAAuB,EAAE,gBAAyB;IAChH,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,CAAC;IACxC,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CACxC,OAAO,CAAC,KAAK,QAAQ;WAClB,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;WAC3B,sBAAsB,CAAC,GAAG,CAAC,CAAC,CAAC;WAC7B,CAAC,CAAC,cAAc,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;WAC5C,CAAC,CAAC,CAAC,gBAAgB,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CACtD,CAAC;AACJ,CAAC;AAOD;;;;qEAIqE;AACrE,SAAS,yBAAyB,CAAC,IAAqB;IACtD,OAAO,OAAO,IAAI,EAAE,WAAW,KAAK,QAAQ;WACvC,CAAC,IAAI,CAAC,gBAAgB,KAAK,yBAAyB;eAClD,IAAI,CAAC,gBAAgB,KAAK,qBAAqB;eAC/C,IAAI,CAAC,gBAAgB,KAAK,UAAU,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;6DAQ6D;AAC7D,MAAM,UAAU,6BAA6B,CAC3C,QAA+C,EAC/C,YAAoB,EACpB,cAAuB;IAEvB,IAAI,QAAiB,CAAC;IACtB,KAAK,MAAM,GAAG,IAAI,QAAQ,IAAI,EAAE,EAAE,CAAC;QACjC,IAAI,GAAG,CAAC,IAAI,EAAE,aAAa,KAAK,YAAY;YAAE,SAAS;QACvD,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,SAAS;QACvE,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QACnD,QAAQ,GAAG,GAAG,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAC5C,CAAC;IACD,OAAO,4BAA4B,CAAC,QAAQ,EAAE,cAAc,EAAE,YAAY,KAAK,UAAU,CAAC,CAAC;AAC7F,CAAC"}

package/dist/lib/localBinding.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Repo-local binding resolution — turns what `.productbrain/config.local.json` declares into a
+ * credential, or refuses outright.
+ *
+ * Ordinary commands (`resolveConfig()` / `loadEnv()`) and `resolveAdminConfig()` share
+ * `resolvePinnedProfile()` so the pin validity bar cannot drift (STA-3 / TEN-3239). Admin still
+ * owns its own cascade around that helper: it never reads config.json siteUrl, CWD .env files, or
+ * preview / local-binding keys. Fail loud, fail closed, fail fast (RULE-268); default closed,
+ * explicitly opened (PRI-22).
+ */
+import { type LocalProjectConfig } from './projectConfig.js';
+/**
+ * Resolve the repo-local profile pin to a credential, or refuse outright.
+ *
+ * FAILS CLOSED on a DANGLING pin: a pin naming a profile that has since been deleted, or whose
+ * file carries no key, must NEVER fall through to the global active profile. The repo has
+ * explicitly declared its tenant; substituting a different one silently retargets every read AND
+ * write at a foreign workspace, and the gateway derives the workspace from the credential (BR-18)
+ * — so nothing downstream catches it.
+ *
+ * INS-2455 is the admin-path instance of exactly this fall-through. Admin now calls this helper
+ * too; a present-but-malformed key is a broken pin, not a credential.
+ */
+export declare function resolvePinnedProfile(profileName: string): {
+    apiKey: string;
+    siteUrl?: string;
+};
+/**
+ * Does `config.local.json` CLAIM a direct credential binding of its own?
+ *
+ * The claim is the `preview` marker OR a credential — see `resolveLocalBinding()` below for why
+ * the marker alone is not the test. A claim is only a question, never an answer: it says the file
+ * MEANT to bind, not that it can. Use `bindsCompletely()` to decide whether a tenant is actually
+ * named.
+ */
+export declare function declaresLocalBinding(localConfig: LocalProjectConfig | null): localConfig is LocalProjectConfig;
+/**
+ * Does `config.local.json` declare a COMPLETE PREVIEW binding — independent of the environment?
+ *
+ * The env-independence is the whole point (Codex P2 r4). `config.ts`'s `getPreviewBinding()` asks
+ * a different question — "is a preview binding what pb is EFFECTIVELY using right now" — so it
+ * bails whenever `PRODUCTBRAIN_API_KEY` is set. But `loadEnv()` COPIES the preview key into that
+ * very variable, so after any command has resolved config, that question answers "no" on a
+ * genuinely preview-bound worktree. Reporting surfaces need the file's own declaration, and
+ * handle the env-override case separately and earlier (reportedProfile.ts's startup snapshot).
+ *
+ * Shared rather than copied so the completeness bar cannot drift (STA-3) — it is the same
+ * `bindsCompletely` (SF-3 atomic apiKey+siteUrl) both callers already depend on.
+ */
+export declare function declaresCompletePreviewBinding(localConfig: LocalProjectConfig | null): {
+    workspaceName: string | null;
+} | null;
+/**
+ * Refuse when a project has declared itself (committed config.json) but named no tenant.
+ *
+ * A dangling pin is a different refusal (`resolvePinnedProfile`). This is the no-tenant case:
+ * config.json says "I am a Product Brain project" and nothing in config.local.json — neither a
+ * pin nor a direct/preview binding — says which workspace. Falling through to the global profile
+ * is the incident. A directory with no config.json is not a project — personal capture and
+ * `pb login` stay open.
+ *
+ * Call after the pin / preview-binding steps, before any global fallback. Those earlier steps
+ * already returned or threw when a tenant was claimed; this still re-checks the binding claim
+ * because `resolveAdminConfig()` has no binding step of its own and must not mistake a
+ * preview-bound worktree for an unpinned one.
+ */
+export declare function refuseWhenProjectHasNoTenant(): void;
+/**
+ * Resolve the direct credential binding in config.local.json, or null when the file does not
+ * claim one (the profile pin then owns resolution).
+ *
+ * The claim is the `preview` marker OR a credential of its own — deliberately NOT the marker
+ * alone. A file carrying an apiKey is asserting which workspace this repo talks to whether or not
+ * `pb:preview` stamped the marker, so gating on the marker would let a hand-written or
+ * partially-scrubbed binding be skipped and a sibling profile pin silently supply a different
+ * tenant's credential instead (the failure class TEN-3237/TEN-3238 closed for the pin path).
+ *
+ * Once claimed, only the atomic apiKey+siteUrl pair (SF-3) may bind — never a preview key paired
+ * with config.json's real-dev gateway (STD-261). Anything else refuses here, ahead of the pin, so
+ * a broken binding is named rather than routed around.
+ */
+export declare function resolveLocalBinding(localConfig: LocalProjectConfig | null): {
+    apiKey: string;
+    siteUrl: string;
+} | null;
+//# sourceMappingURL=localBinding.d.ts.map

package/dist/lib/localBinding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localBinding.d.ts","sourceRoot":"","sources":["../../src/lib/localBinding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAA+C,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAG1G;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAqB9F;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,kBAAkB,GAAG,IAAI,GACrC,WAAW,IAAI,kBAAkB,CAKnC;AAmBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,WAAW,EAAE,kBAAkB,GAAG,IAAI,GACrC;IAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAGzC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAiCnD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,kBAAkB,GAAG,IAAI,GACrC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAwB5C"}