@productbrain/cli 0.1.0-beta.914 → 0.1.0-beta.9145

package/dist/lib/legalRelationTypes.d.ts

@@ -0,0 +1,19 @@
+/** 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;
+    } | null;
+};
+/** Resolves the declared `valid_relation_types` for `canonicalKey` out of a semantic-types
+ *  listEntries result. The server answers that read from its code catalog (DEC-1949,
+ *  convex/chain/semanticTypes.ts typeCatalogRowsForWorkspace): one accepted, well-formed row per
+ *  active type, so the row for the key is the one to read. 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":"AA8CA;;;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,CAAA;KAAE,GAAG,IAAI,CAAC;CAC3E,CAAC;AAEF;;;;cAIc;AACd,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI,GAAG,SAAS,EAC/C,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,OAAO,GACtB,MAAM,EAAE,CAGV"}

package/dist/lib/legalRelationTypes.js

@@ -0,0 +1,64 @@
+/**
+ * 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
+ *     type's declared `valid_relation_types` lists (guards.ts:302-307), so such a verb is never
+ *     offered as a `pb relate` recovery verb.
+ *   - 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';
+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)));
+}
+/** Resolves the declared `valid_relation_types` for `canonicalKey` out of a semantic-types
+ *  listEntries result. The server answers that read from its code catalog (DEC-1949,
+ *  convex/chain/semanticTypes.ts typeCatalogRowsForWorkspace): one accepted, well-formed row per
+ *  active type, so the row for the key is the one to read. Then filters to what `pb relate` can
+ *  create. */
+export function resolveCreatableRelationTypes(typeRows, canonicalKey, targetIsDomain) {
+    const row = (typeRows ?? []).find((r) => r.data?.canonical_key === canonicalKey);
+    return filterCreatableRelationTypes(row?.data?.valid_relation_types, 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,sBAAsB,IAAI,2BAA2B,EAAE,MAAM,yCAAyC,CAAC;AAEhH,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;AAMD;;;;cAIc;AACd,MAAM,UAAU,6BAA6B,CAC3C,QAA+C,EAC/C,YAAoB,EACpB,cAAuB;IAEvB,MAAM,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,aAAa,KAAK,YAAY,CAAC,CAAC;IACjF,OAAO,4BAA4B,CAAC,GAAG,EAAE,IAAI,EAAE,oBAAoB,EAAE,cAAc,EAAE,YAAY,KAAK,UAAU,CAAC,CAAC;AACpH,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"}

package/dist/lib/localBinding.js

@@ -0,0 +1,173 @@
+/**
+ * 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 { ConfigResolutionError } from './configResult.js';
+import { ErrorCode } from './errors.js';
+import { resolveNamedProfileConfig } from './profiles.js';
+import { readLocalProjectConfig, projectConfigExists } from './projectConfig.js';
+import { API_KEY_PREFIX } from './tokenConstants.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 function resolvePinnedProfile(profileName) {
+    const namedConfig = resolveNamedProfileConfig(profileName);
+    // A present-but-malformed key is a broken pin, not a credential. Accepting it here would
+    // surface as a generic "no API key, run pb login" far downstream, pointing the operator
+    // away from the pin that actually broke.
+    if (!namedConfig?.apiKey?.startsWith(API_KEY_PREFIX)) {
+        throw new ConfigResolutionError(`This repo is pinned to profile "${profileName}" (.productbrain/config.local.json), ` +
+            `but that profile has no valid API key — it may have been deleted or never fully set up. ` +
+            `Refusing to silently fall back to a different workspace. ` +
+            `Run \`pb profile use --local <profile>\` to fix the pin, or \`pb profile create ${profileName}\` to restore it.`, {
+            code: ErrorCode.AUTH_MISSING,
+            category: 'auth',
+            kind: 'profile-pin',
+            nextCommand: 'pb profile use --local <profile>',
+            guidance: 'Run `pb profile use --local <profile>` to fix the repo pin.',
+        });
+    }
+    return { apiKey: namedConfig.apiKey, siteUrl: namedConfig.siteUrl };
+}
+/**
+ * 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 function declaresLocalBinding(localConfig) {
+    if (!localConfig)
+        return false;
+    return (localConfig.preview === true || Boolean(localConfig.apiKey) || localConfig.apiKeyMalformed === true);
+}
+/**
+ * Does `config.local.json` carry a COMPLETE binding — the atomic apiKey+siteUrl pair (SF-3)?
+ *
+ * This, not the claim above, is what "the repo names a tenant" means. `resolveLocalBinding()`
+ * rejects a claimed-but-incomplete binding, but `resolveAdminConfig()` has no binding step to do
+ * that rejecting — so if `refuseWhenProjectHasNoTenant()` accepted a mere claim, a broken binding
+ * (`{ preview: true }` alone, a key with no siteUrl, a malformed key) would wave admin straight
+ * past the refusal into the global profile, which defaults to production (WP-681/INS-2455 is that
+ * exact incident). Shared by both so the bar cannot drift (STA-3), and it is the spec's own word:
+ * a *complete* preview binding is what stays unchanged.
+ */
+function bindsCompletely(localConfig) {
+    return Boolean(localConfig?.apiKey && localConfig.siteUrl);
+}
+/**
+ * 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 function declaresCompletePreviewBinding(localConfig) {
+    if (localConfig?.preview !== true || !bindsCompletely(localConfig))
+        return null;
+    return { workspaceName: localConfig.workspaceName ?? 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 function refuseWhenProjectHasNoTenant() {
+    // The declaration is the FILE, not its contents — a corrupt config.json must not read as
+    // "not a project" and reopen the fall-through exactly when the committed file is damaged.
+    if (!projectConfigExists())
+        return;
+    const localConfig = readLocalProjectConfig();
+    if (localConfig?.profile)
+        return;
+    // A COMPLETE direct/preview binding names a tenant too: `npm run pb:preview` writes apiKey +
+    // siteUrl and no `profile` field. resolveConfig()/loadEnv() already returned at their own
+    // binding step, so this only reaches the admin cascade — which by design does not consume
+    // preview keys, and without this would call a legitimately preview-bound worktree untenanted.
+    // COMPLETE, not merely claimed: an incomplete binding names nothing usable, and admin has no
+    // binding step to reject it, so accepting a claim here would route admin to the global profile
+    // (Codex review round 2 — a regression this line introduced and this word closes).
+    if (bindsCompletely(localConfig))
+        return;
+    // Deliberately NOT excepted: `PB_PROFILE`. It looks like an explicit tenant, but exported from
+    // a shell rc it is exactly as ambient as the global active profile whose silent substitution is
+    // the incident — so WP-694 names only an exported PRODUCTBRAIN_API_KEY as the escape hatch, and
+    // this refusal outranks the profile system that reads PB_PROFILE (Codex review, declined).
+    throw new ConfigResolutionError(`This repo is a Product Brain project (.productbrain/config.json) but has no tenant pin ` +
+        `in .productbrain/config.local.json. Refusing to silently use a different workspace. ` +
+        `Run \`pb profile use --local <profile>\` to pin this repo, or \`pb profile list\` to see your profiles.`, {
+        code: ErrorCode.AUTH_MISSING,
+        category: 'auth',
+        kind: 'missing-pin',
+        nextCommand: 'pb profile use --local <profile>',
+        guidance: 'Run `pb profile use --local <profile>` to pin this repo to a workspace.',
+    });
+}
+/**
+ * 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 function resolveLocalBinding(localConfig) {
+    if (!declaresLocalBinding(localConfig))
+        return null;
+    if (bindsCompletely(localConfig)) {
+        return { apiKey: localConfig.apiKey, siteUrl: localConfig.siteUrl.replace(/\/$/, '') };
+    }
+    // A malformed key is present-but-unusable, not absent — readLocalProjectConfig() withholds it
+    // from `apiKey` so it can never bind, and flags it so this refusal can name the real fault.
+    const fault = localConfig.apiKeyMalformed
+        ? `its API key is not a valid ${API_KEY_PREFIX} key`
+        : !localConfig.apiKey
+            ? 'missing API key'
+            : 'missing deployment URL';
+    throw new ConfigResolutionError(`This repo has an incomplete preview binding (.productbrain/config.local.json): ` +
+        `${fault}. Refusing to use its profile pin or another workspace instead.`, {
+        code: ErrorCode.CONFIG_INVALID,
+        category: 'config',
+        kind: 'preview-binding',
+        nextCommand: 'npm run pb:preview',
+        guidance: 'Run `npm run pb:preview` to repair the preview binding, or `npm run pb:real` to return to the repo pin.',
+    });
+}
+//# sourceMappingURL=localBinding.js.map

package/dist/lib/localBinding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localBinding.js","sourceRoot":"","sources":["../../src/lib/localBinding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAA2B,MAAM,oBAAoB,CAAC;AAC1G,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,MAAM,WAAW,GAAG,yBAAyB,CAAC,WAAW,CAAC,CAAC;IAC3D,yFAAyF;IACzF,wFAAwF;IACxF,yCAAyC;IACzC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,qBAAqB,CAC7B,mCAAmC,WAAW,uCAAuC;YACnF,0FAA0F;YAC1F,2DAA2D;YAC3D,mFAAmF,WAAW,mBAAmB,EACnH;YACE,IAAI,EAAE,SAAS,CAAC,YAAY;YAC5B,QAAQ,EAAE,MAAM;YAChB,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,kCAAkC;YAC/C,QAAQ,EAAE,6DAA6D;SACxE,CACF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,EAAE,CAAC;AACtE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAsC;IAEtC,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,CACL,WAAW,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,eAAe,KAAK,IAAI,CACpG,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,eAAe,CACtB,WAAsC;IAEtC,OAAO,OAAO,CAAC,WAAW,EAAE,MAAM,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,8BAA8B,CAC5C,WAAsC;IAEtC,IAAI,WAAW,EAAE,OAAO,KAAK,IAAI,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IAChF,OAAO,EAAE,aAAa,EAAE,WAAW,CAAC,aAAa,IAAI,IAAI,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,4BAA4B;IAC1C,yFAAyF;IACzF,0FAA0F;IAC1F,IAAI,CAAC,mBAAmB,EAAE;QAAE,OAAO;IAEnC,MAAM,WAAW,GAAG,sBAAsB,EAAE,CAAC;IAC7C,IAAI,WAAW,EAAE,OAAO;QAAE,OAAO;IAEjC,6FAA6F;IAC7F,0FAA0F;IAC1F,0FAA0F;IAC1F,8FAA8F;IAC9F,6FAA6F;IAC7F,+FAA+F;IAC/F,mFAAmF;IACnF,IAAI,eAAe,CAAC,WAAW,CAAC;QAAE,OAAO;IAEzC,+FAA+F;IAC/F,gGAAgG;IAChG,gGAAgG;IAChG,2FAA2F;IAC3F,MAAM,IAAI,qBAAqB,CAC7B,yFAAyF;QACvF,sFAAsF;QACtF,yGAAyG,EAC3G;QACE,IAAI,EAAE,SAAS,CAAC,YAAY;QAC5B,QAAQ,EAAE,MAAM;QAChB,IAAI,EAAE,aAAa;QACnB,WAAW,EAAE,kCAAkC;QAC/C,QAAQ,EAAE,yEAAyE;KACpF,CACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,WAAsC;IAEtC,IAAI,CAAC,oBAAoB,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,eAAe,CAAC,WAAW,CAAC,EAAE,CAAC;QACjC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,EAAE,CAAC;IACzF,CAAC;IAED,8FAA8F;IAC9F,4FAA4F;IAC5F,MAAM,KAAK,GAAG,WAAW,CAAC,eAAe;QACvC,CAAC,CAAC,8BAA8B,cAAc,MAAM;QACpD,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM;YACnB,CAAC,CAAC,iBAAiB;YACnB,CAAC,CAAC,wBAAwB,CAAC;IAC/B,MAAM,IAAI,qBAAqB,CAC7B,iFAAiF;QAC/E,GAAG,KAAK,iEAAiE,EAC3E;QACE,IAAI,EAAE,SAAS,CAAC,cAAc;QAC9B,QAAQ,EAAE,QAAQ;QAClB,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE,oBAAoB;QACjC,QAAQ,EAAE,yGAAyG;KACpH,CACF,CAAC;AACJ,CAAC"}

package/dist/lib/method-registry.d.ts

@@ -1,6 +1,15 @@
 /**
  * method-registry.ts — load pb method registry (WP-310 E4).
- * Chain-first with bundled fallback. Used during handshake when manifest is present.
+ *
+ * Loads the BUNDLED registry JSON. Used during handshake when a manifest is present.
+ *
+ * History (TEN-2783): this used to be "Chain-first with bundled fallback", attempting a
+ * `chain.getMethodRegistry` gateway call before falling back. That route was never registered in
+ * the gateway (absent from `packages/kernel-client/src/generated/routes.generated.ts`), so the
+ * call threw on every handshake since introduction and the bundled path was ALWAYS the real one.
+ * The dead attempt was removed so the bundled registry is the honest, single primary — no
+ * misleading `source: 'chain'` that could never occur, no orphan `chain.getMethodRegistry` call
+ * for the called-route gate to carve out.
  */
 export interface RegistryMethod {
     name: string;
@@ -14,19 +23,15 @@ export interface MethodRegistry {
 }
 export interface RegistryLoadResult {
     registry: MethodRegistry;
-    source: 'chain' | 'bundled';
-    /** true when source is 'bundled' and generatedAt is older than FRESHNESS_DAYS */
+    /** Always 'bundled' — the Chain path (TEN-2783) was removed; kept as a field for report output. */
+    source: 'bundled';
+    /** true when the bundled registry's generatedAt is older than FRESHNESS_DAYS */
     stale: boolean;
 }
 /**
- * Load the pb method registry.
- *
- * @param methodSource - from manifest.method_source: 'chain' | 'bundled' | undefined
- * @param chainFetch   - function that calls a Chain API endpoint (kernelCall signature)
+ * Load the pb method registry from the bundled JSON.
  *
- * Resolution order:
- *   - 'bundled' → skip Chain, load bundled JSON
- *   - 'chain' or undefined → try Chain first; on error fall through to bundled
+ * Async to preserve the caller's `.catch(() => null)` on a read failure (missing/corrupt bundle).
  */
-export declare function loadMethodRegistry(methodSource: 'chain' | 'bundled' | undefined, chainFetch: (fn: string, args: Record<string, unknown>) => Promise<unknown>): Promise<RegistryLoadResult>;
+export declare function loadMethodRegistry(): Promise<RegistryLoadResult>;
 //# sourceMappingURL=method-registry.d.ts.map

package/dist/lib/method-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"method-registry.d.ts","sourceRoot":"","sources":["../../src/lib/method-registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,iFAAiF;IACjF,KAAK,EAAE,OAAO,CAAC;CAChB;AAoBD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,EAC7C,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,GAC1E,OAAO,CAAC,kBAAkB,CAAC,CAoB7B"}
+{"version":3,"file":"method-registry.d.ts","sourceRoot":"","sources":["../../src/lib/method-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,cAAc,CAAC;IACzB,mGAAmG;IACnG,MAAM,EAAE,SAAS,CAAC;IAClB,gFAAgF;IAChF,KAAK,EAAE,OAAO,CAAC;CAChB;AAoBD;;;;GAIG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,kBAAkB,CAAC,CAGtE"}

package/dist/lib/method-registry.js

@@ -1,6 +1,15 @@
 /**
  * method-registry.ts — load pb method registry (WP-310 E4).
- * Chain-first with bundled fallback. Used during handshake when manifest is present.
+ *
+ * Loads the BUNDLED registry JSON. Used during handshake when a manifest is present.
+ *
+ * History (TEN-2783): this used to be "Chain-first with bundled fallback", attempting a
+ * `chain.getMethodRegistry` gateway call before falling back. That route was never registered in
+ * the gateway (absent from `packages/kernel-client/src/generated/routes.generated.ts`), so the
+ * call threw on every handshake since introduction and the bundled path was ALWAYS the real one.
+ * The dead attempt was removed so the bundled registry is the honest, single primary — no
+ * misleading `source: 'chain'` that could never occur, no orphan `chain.getMethodRegistry` call
+ * for the called-route gate to carve out.
  */
 import { readFileSync } from 'fs';
 import { join } from 'path';
@@ -21,32 +30,11 @@ function isStaleFn(generatedAt) {
     return now - generated > FRESHNESS_DAYS * 24 * 60 * 60 * 1000;
 }
 /**
- * Load the pb method registry.
- *
- * @param methodSource - from manifest.method_source: 'chain' | 'bundled' | undefined
- * @param chainFetch   - function that calls a Chain API endpoint (kernelCall signature)
+ * Load the pb method registry from the bundled JSON.
  *
- * Resolution order:
- *   - 'bundled' → skip Chain, load bundled JSON
- *   - 'chain' or undefined → try Chain first; on error fall through to bundled
+ * Async to preserve the caller's `.catch(() => null)` on a read failure (missing/corrupt bundle).
  */
-export async function loadMethodRegistry(methodSource, chainFetch) {
-    // Explicitly bundled — skip Chain attempt
-    if (methodSource === 'bundled') {
-        const registry = loadBundled();
-        return { registry, source: 'bundled', stale: isStaleFn(registry.generatedAt) };
-    }
-    // method_source: 'chain' or undefined — try Chain first
-    try {
-        const data = await chainFetch('chain.getMethodRegistry', {});
-        if (data && typeof data === 'object' && 'methods' in data) {
-            return { registry: data, source: 'chain', stale: false };
-        }
-    }
-    catch {
-        // Chain unreachable or returned unexpected shape — fall through to bundled
-    }
-    // Bundled fallback
+export async function loadMethodRegistry() {
     const registry = loadBundled();
     return { registry, source: 'bundled', stale: isStaleFn(registry.generatedAt) };
 }

package/dist/lib/method-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"method-registry.js","sourceRoot":"","sources":["../../src/lib/method-registry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAqBpC,iGAAiG;AACjG,wFAAwF;AACxF,wGAAwG;AACxG,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,MAAM,qBAAqB,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAC;AAC/F,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB,SAAS,WAAW;IAClB,MAAM,GAAG,GAAG,YAAY,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;AAC3C,CAAC;AAED,SAAS,SAAS,CAAC,WAAmB;IACpC,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,OAAO,GAAG,GAAG,SAAS,GAAG,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAChE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,YAA6C,EAC7C,UAA2E;IAE3E,0CAA0C;IAC1C,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;QAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;IACjF,CAAC;IAED,wDAAwD;IACxD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,yBAAyB,EAAE,EAAE,CAAC,CAAC;QAC7D,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;YAC1D,OAAO,EAAE,QAAQ,EAAE,IAAsB,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC7E,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;IAC7E,CAAC;IAED,mBAAmB;IACnB,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;AACjF,CAAC"}
+{"version":3,"file":"method-registry.js","sourceRoot":"","sources":["../../src/lib/method-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAsBpC,iGAAiG;AACjG,wFAAwF;AACxF,wGAAwG;AACxG,MAAM,SAAS,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,MAAM,qBAAqB,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAC;AAC/F,MAAM,cAAc,GAAG,CAAC,CAAC;AAEzB,SAAS,WAAW;IAClB,MAAM,GAAG,GAAG,YAAY,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;IACxD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;AAC3C,CAAC;AAED,SAAS,SAAS,CAAC,WAAmB;IACpC,MAAM,SAAS,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,OAAO,GAAG,GAAG,SAAS,GAAG,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB;IACtC,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;IAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;AACjF,CAAC"}

package/dist/lib/normalizeMaterializedFilename.d.ts

@@ -2,9 +2,9 @@
  * normalizeMaterializedFilename — WP-379 S5b
  *
  * Produces a lowercase, slug-friendly filename from an asset name.
- * Used by resolveProjectionCollision to compare on-disk filenames (which may
- * have been projected with a non-normalized case) against the canonical
- * lowercase form that handshake now writes.
+ * Used by findLeftoverProjections/findLeftoverCursorSkills to compare on-disk filenames (which
+ * may have been projected with a non-normalized case) against the canonical lowercase form
+ * that handshake now writes.
  *
  * Contract:
  *   - Output is lowercase.

package/dist/lib/normalizeMaterializedFilename.js

@@ -2,9 +2,9 @@
  * normalizeMaterializedFilename — WP-379 S5b
  *
  * Produces a lowercase, slug-friendly filename from an asset name.
- * Used by resolveProjectionCollision to compare on-disk filenames (which may
- * have been projected with a non-normalized case) against the canonical
- * lowercase form that handshake now writes.
+ * Used by findLeftoverProjections/findLeftoverCursorSkills to compare on-disk filenames (which
+ * may have been projected with a non-normalized case) against the canonical lowercase form
+ * that handshake now writes.
  *
  * Contract:
  *   - Output is lowercase.

package/dist/lib/notice-marker.d.ts

@@ -0,0 +1,3 @@
+/** Returns true exactly once per (channel, session/day). Never throws. */
+export declare function claimNotice(channel: 'agent' | 'human'): boolean;
+//# sourceMappingURL=notice-marker.d.ts.map

package/dist/lib/notice-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notice-marker.d.ts","sourceRoot":"","sources":["../../src/lib/notice-marker.ts"],"names":[],"mappings":"AA+KA,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAsB/D"}