@rigour-labs/core 6.2.5 → 6.3.1

package/dist/semantic/rules/degraded-response-cached.js

@@ -0,0 +1,271 @@
+/**
+ * degraded-response-cached: an HTTP response that can carry a failure
+ * fallback is sent with a positive max-age.
+ *
+ * A read that fails is often caught and replaced with null or a default so
+ * the rest of the answer still renders. If that degraded answer is cached,
+ * clients keep serving it after the failure recovers. The rule proves both
+ * halves: the body derives from a function that returns a fallback from a
+ * `catch`, and the cache header is set without any condition on the body.
+ */
+import ts from 'typescript';
+import { calledFunction, enclosingFunction, forEachNode, forEachOwnNode, lineOf, locationOf, propertyNameText, relativeFile, snippet, symbolOf, unwrap } from '../ast.js';
+import { originsOf, propertyValues } from '../origins.js';
+const POSITIVE_CACHE = /(?:^|[\s,])(?:s-)?max-age\s*=\s*[1-9]/i;
+const RESPONSE_CLASSES = new Set(['Response', 'NextResponse']);
+export const degradedResponseCached = {
+    id: 'degraded-response-cached',
+    check(ctx) {
+        const findings = [];
+        forEachNode(ctx.sourceFile, (node) => {
+            if (!ts.isCallExpression(node) && !ts.isNewExpression(node))
+                return;
+            const finding = responseParts(node) ? checkDirect(ctx, node) : ts.isCallExpression(node) ? checkCall(ctx, node) : null;
+            if (finding)
+                findings.push(finding);
+        });
+        return findings;
+    },
+};
+/** `Response.json(body, init)`, `NextResponse.json(...)`, `new Response(body, init)`. */
+function responseParts(node) {
+    const args = node.arguments ?? ts.factory.createNodeArray();
+    if (args.length < 2)
+        return null;
+    const callee = unwrap(node.expression);
+    const isJson = ts.isCallExpression(node) && ts.isPropertyAccessExpression(callee) && callee.name.text === 'json'
+        && ts.isIdentifier(callee.expression) && RESPONSE_CLASSES.has(callee.expression.text);
+    const isNew = ts.isNewExpression(node) && ts.isIdentifier(callee) && RESPONSE_CLASSES.has(callee.text);
+    return isJson || isNew ? { body: args[0], init: args[1] } : null;
+}
+/** A response built in place from a fallback-derived body, cached without a condition on it. */
+function checkDirect(ctx, node) {
+    const { body, init } = responseParts(node);
+    const fallback = fallbackIn(ctx, body);
+    if (!fallback)
+        return null;
+    const bodySymbols = identifierSymbols(ctx.checker, body);
+    const entry = cacheEntries(ctx.checker, init).find(e => POSITIVE_CACHE.test(e.value.text)
+        && !e.guards.some(g => [...identifierSymbols(ctx.checker, g)].some(s => bodySymbols.has(s))));
+    return entry ? finding(ctx, node, entry, fallback) : null;
+}
+/** A call to a function that caches one of its parameters, passed a fallback-derived value. */
+function checkCall(ctx, call) {
+    const fn = calledFunction(ctx.checker, call);
+    if (!fn)
+        return null;
+    for (const [index, entry] of cachedParams(ctx.summaries, fn)) {
+        const arg = call.arguments[index];
+        const fallback = arg ? fallbackIn(ctx, arg) : null;
+        if (fallback)
+            return finding(ctx, call, entry, fallback);
+    }
+    return null;
+}
+function cachedParams(summaries, fn) {
+    return summaries.memo('degraded-response-cached:cached-params', fn, new Map(), () => {
+        const params = new Map();
+        const checker = summaries.checker;
+        forEachOwnNode(fn, (node) => {
+            if (!ts.isCallExpression(node) && !ts.isNewExpression(node))
+                return;
+            const parts = responseParts(node);
+            if (!parts)
+                return;
+            for (const index of bodyParams(checker, parts.body, fn)) {
+                const param = checker.getSymbolAtLocation(fn.parameters[index].name);
+                const entry = cacheEntries(checker, parts.init).find(e => POSITIVE_CACHE.test(e.value.text)
+                    && !(param && e.guards.some(g => identifierSymbols(checker, g).has(param))));
+                if (entry)
+                    params.set(index, entry);
+            }
+        });
+        return params;
+    });
+}
+/** Parameters of `fn` that become the response body, directly or spread into it. */
+function bodyParams(checker, body, fn) {
+    const indices = [];
+    const collect = (origin) => {
+        if (origin.kind === 'param' && origin.fn === fn)
+            indices.push(origin.index);
+    };
+    for (const origin of originsOf(checker, body)) {
+        collect(origin);
+        if (origin.kind !== 'object')
+            continue;
+        for (const spread of propertyValues(checker, origin.node, '').spreads)
+            originsOf(checker, spread).forEach(collect);
+    }
+    return indices;
+}
+/** Every `cache-control` value in an init's headers, with the conditions guarding it. */
+function cacheEntries(checker, init) {
+    const entries = [];
+    for (const origin of originsOf(checker, init)) {
+        if (origin.kind !== 'object')
+            continue;
+        for (const headers of propertyValues(checker, origin.node, 'headers').values) {
+            collectHeaderEntries(checker, headers, [], entries, 0);
+        }
+    }
+    return entries;
+}
+function collectHeaderEntries(checker, expr, guards, into, depth) {
+    if (depth > 6)
+        return;
+    const node = unwrap(expr);
+    if (ts.isConditionalExpression(node)) {
+        collectHeaderEntries(checker, node.whenTrue, [...guards, node.condition], into, depth + 1);
+        collectHeaderEntries(checker, node.whenFalse, [...guards, node.condition], into, depth + 1);
+        return;
+    }
+    if (ts.isIdentifier(node)) {
+        for (const origin of originsOf(checker, node)) {
+            if (origin.kind === 'object')
+                collectHeaderEntries(checker, origin.node, guards, into, depth + 1);
+        }
+        return;
+    }
+    if (!ts.isObjectLiteralExpression(node))
+        return;
+    for (const prop of node.properties) {
+        if (ts.isSpreadAssignment(prop))
+            collectHeaderEntries(checker, prop.expression, guards, into, depth + 1);
+        else if (ts.isPropertyAssignment(prop) && propertyNameText(prop.name)?.toLowerCase() === 'cache-control') {
+            collectValues(prop.initializer, guards, into);
+        }
+    }
+}
+function collectValues(expr, guards, into) {
+    const node = unwrap(expr);
+    if (ts.isStringLiteralLike(node))
+        into.push({ value: node, guards });
+    else if (ts.isConditionalExpression(node)) {
+        collectValues(node.whenTrue, [...guards, node.condition], into);
+        collectValues(node.whenFalse, [...guards, node.condition], into);
+    }
+}
+/** The catch-fallback a value can carry, found through calls, spreads and property values. */
+function fallbackIn(ctx, expr) {
+    return fallbackOf(ctx.summaries, expr, 0);
+}
+function fallbackOf(summaries, expr, depth) {
+    if (depth > 4)
+        return null;
+    for (const origin of originsOf(summaries.checker, expr)) {
+        if (origin.kind === 'call') {
+            const fn = calledFunction(summaries.checker, origin.node);
+            // A call with no source body (JSON.stringify, String) passes its arguments' values through.
+            const found = fn ? returnsFallback(summaries, fn) : fallbackInArguments(summaries, origin.node, depth);
+            if (found)
+                return found;
+        }
+        if (origin.kind === 'object') {
+            for (const part of objectParts(origin.node)) {
+                for (const id of identifiersIn(part)) {
+                    const found = fallbackOf(summaries, id, depth + 1);
+                    if (found)
+                        return found;
+                }
+            }
+        }
+    }
+    return null;
+}
+function fallbackInArguments(summaries, call, depth) {
+    for (const arg of call.arguments) {
+        const found = fallbackOf(summaries, arg, depth + 1);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Whether `fn` can return a value produced by a failure fallback, and where. */
+function returnsFallback(summaries, fn) {
+    return summaries.memo('degraded-response-cached:fallback', fn, null, () => {
+        let found = null;
+        forEachOwnNode(fn, (node) => {
+            if (found || !ts.isReturnStatement(node))
+                return;
+            if (isInsideCatch(node, fn) && isFallbackValue(node.expression))
+                found = { fn, node };
+            else if (node.expression)
+                found = fallbackOf(summaries, node.expression, 1);
+        });
+        if (!found && !ts.isBlock(fn.body) && fn.body)
+            found = fallbackOf(summaries, fn.body, 1);
+        return found;
+    });
+}
+function isInsideCatch(node, fn) {
+    for (let current = node.parent; current && current !== fn; current = current.parent) {
+        if (ts.isCatchClause(current))
+            return enclosingFunction(current) === fn;
+    }
+    return false;
+}
+/** `return;`, `return null`, `return undefined`, `return []`, `return {}`, `return false`. */
+function isFallbackValue(expr) {
+    if (!expr)
+        return true;
+    const node = unwrap(expr);
+    return node.kind === ts.SyntaxKind.NullKeyword || node.kind === ts.SyntaxKind.FalseKeyword
+        || (ts.isIdentifier(node) && node.text === 'undefined')
+        || (ts.isArrayLiteralExpression(node) && node.elements.length === 0)
+        || (ts.isObjectLiteralExpression(node) && node.properties.length === 0);
+}
+/** Property values and spreads of an object literal. */
+function objectParts(obj) {
+    const parts = [];
+    for (const prop of obj.properties) {
+        if (ts.isPropertyAssignment(prop))
+            parts.push(prop.initializer);
+        else if (ts.isShorthandPropertyAssignment(prop))
+            parts.push(prop.name);
+        else if (ts.isSpreadAssignment(prop))
+            parts.push(prop.expression);
+    }
+    return parts;
+}
+function identifiersIn(expr) {
+    const ids = [];
+    const walk = (node) => {
+        if (ts.isIdentifier(node))
+            ids.push(node);
+        else if (!ts.isPropertyAccessExpression(node))
+            ts.forEachChild(node, walk);
+        else
+            walk(node.expression);
+    };
+    walk(expr);
+    return ids;
+}
+function identifierSymbols(checker, expr) {
+    const symbols = new Set();
+    const walk = (node) => {
+        if (ts.isIdentifier(node)) {
+            const symbol = symbolOf(checker, node);
+            if (symbol)
+                symbols.add(symbol);
+        }
+        ts.forEachChild(node, walk);
+    };
+    walk(expr);
+    return symbols;
+}
+function finding(ctx, node, entry, fallback) {
+    const fnName = fallback.fn.name && ts.isIdentifier(fallback.fn.name) ? fallback.fn.name.text : 'a function';
+    return {
+        rule: 'degraded-response-cached',
+        severity: 'medium',
+        provenance: 'traditional',
+        file: relativeFile(ctx.cwd, ctx.sourceFile),
+        line: lineOf(node),
+        message: `This response is cached (\`cache-control: ${entry.value.text}\`, ${locationOf(ctx.cwd, entry.value)}) `
+            + `but its body can carry the fallback \`${fnName}\` returns when a read fails (${locationOf(ctx.cwd, fallback.node)}). `
+            + `A degraded answer then stays cached after the failure recovers.`,
+        hint: 'Send `no-store` when any part of the answer is a fallback (for example `cache-control: body.complete ? "private, max-age=300" : "no-store"`).',
+        evidence: [`${locationOf(ctx.cwd, entry.value)} ${snippet(entry.value)}`, `${locationOf(ctx.cwd, fallback.node)} ${snippet(fallback.node)}`],
+    };
+}

package/dist/semantic/rules/in-memory-aggregation.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticRule } from '../types.js';
+export declare const inMemoryAggregation: SemanticRule;

package/dist/semantic/rules/in-memory-aggregation.js

@@ -0,0 +1,179 @@
+/**
+ * in-memory-aggregation: every page of a paged read is collected into an
+ * array that is then only counted or capped.
+ *
+ * Work and memory grow with the table. A size cap that throws does not bound
+ * the cost; it turns growth into an outage once the data passes the cap.
+ * Counting belongs in the data store (count / group by) or a paged fold.
+ */
+import ts from 'typescript';
+import { calleeName, forEachNode, forEachOwnNode, isFunctionLike, lineOf, relativeFile, snippet, symbolOf, unwrap } from '../ast.js';
+const PAGED_CALL = /(?:fetch|read|get|list|load|query|select)All|all(?:Pages|Rows|Records)|paginat|eachPage|forEachPage/i;
+const PAGE_CURSOR = /^(?:cursor|offset|page|pageToken|nextToken|after|skip|next|startAfter)$/i;
+const AGGREGATE_METHODS = new Set(['length', 'reduce', 'some', 'every', 'includes', 'find', 'findIndex', 'indexOf']);
+export const inMemoryAggregation = {
+    id: 'in-memory-aggregation',
+    check(ctx) {
+        const findings = [];
+        forEachNode(ctx.sourceFile, (node) => {
+            if (isFunctionLike(node) && node.body)
+                findings.push(...checkFunction(ctx, node));
+        });
+        return findings;
+    },
+};
+function checkFunction(ctx, fn) {
+    const findings = [];
+    forEachOwnNode(fn, (node) => {
+        if (!ts.isVariableDeclaration(node) || !ts.isIdentifier(node.name) || !node.initializer)
+            return;
+        const init = unwrap(node.initializer);
+        if (!ts.isArrayLiteralExpression(init) || init.elements.length > 0)
+            return;
+        const symbol = ctx.checker.getSymbolAtLocation(node.name);
+        if (!symbol)
+            return;
+        const finding = checkAccumulator(ctx, fn, node.name, symbol);
+        if (finding)
+            findings.push(finding);
+    });
+    return findings;
+}
+function checkAccumulator(ctx, fn, name, symbol) {
+    const refs = references(ctx.checker, fn, symbol, name);
+    const fills = refs.filter(isPushTarget);
+    const pagedFill = fills.find(ref => isPagedFill(ref, fn));
+    if (!pagedFill)
+        return null;
+    const others = refs.filter(ref => !isPushTarget(ref));
+    const capGuard = others.find(isThrowingSizeCap);
+    if (!capGuard && !(others.length > 0 && others.every(isAggregateUse)))
+        return null;
+    const pushCall = pagedFill.parent.parent;
+    const reason = capGuard
+        ? `then capped with \`${snippet(capGuard.parent.parent, 50)}\``
+        : 'and then only counted';
+    return {
+        rule: 'in-memory-aggregation',
+        severity: 'high',
+        provenance: 'traditional',
+        file: relativeFile(ctx.cwd, ctx.sourceFile),
+        line: lineOf(pushCall),
+        message: `\`${name.text}\` collects every page of a paged read in memory (\`${snippet(pushCall, 70)}\`) ${reason}. `
+            + `Time and memory grow with the table, and a cap that throws fails every request once the data passes it.`,
+        hint: 'Aggregate where the data lives (count / group by in SQL or an RPC), or fold each page into running totals instead of keeping all rows.',
+        evidence: [`${relativeFile(ctx.cwd, ctx.sourceFile)}:${lineOf(pushCall)} ${snippet(pushCall, 70)}`],
+    };
+}
+function references(checker, fn, symbol, declName) {
+    const refs = [];
+    forEachOwnNode(fn, (node) => {
+        if (ts.isIdentifier(node) && node !== declName && symbolOf(checker, node) === symbol)
+            refs.push(node);
+    });
+    return refs;
+}
+/** `ref.push(...)` */
+function isPushTarget(ref) {
+    const access = ref.parent;
+    return ts.isPropertyAccessExpression(access) && access.expression === ref && access.name.text === 'push'
+        && ts.isCallExpression(access.parent) && access.parent.expression === access;
+}
+function isPagedFill(ref, fn) {
+    const call = ref.parent.parent;
+    if (call.arguments.some(arg => containsAwaitedCall(arg, name => PAGED_CALL.test(name))))
+        return true;
+    const loop = enclosingLoop(call, fn);
+    return !!loop && containsCursorDrivenAwait(loop);
+}
+function containsAwaitedCall(node, matches) {
+    let found = false;
+    const walk = (n) => {
+        if (found)
+            return;
+        if (ts.isAwaitExpression(n)) {
+            const awaited = unwrap(n.expression);
+            if (ts.isCallExpression(awaited)) {
+                const name = calleeName(awaited);
+                if (name && matches(name))
+                    found = true;
+            }
+        }
+        if (!found)
+            ts.forEachChild(n, walk);
+    };
+    walk(node);
+    return found;
+}
+function enclosingLoop(node, fn) {
+    for (let current = node.parent; current && current !== fn; current = current.parent) {
+        if (ts.isForStatement(current) || ts.isWhileStatement(current) || ts.isDoStatement(current))
+            return current;
+    }
+    return undefined;
+}
+/** An awaited call inside the loop whose arguments mention a page cursor. */
+function containsCursorDrivenAwait(loop) {
+    let found = false;
+    const walk = (n) => {
+        if (found)
+            return;
+        if (ts.isAwaitExpression(n) && ts.isCallExpression(unwrap(n.expression))) {
+            const call = unwrap(n.expression);
+            found = call.arguments.some(arg => mentionsCursor(arg));
+        }
+        if (!found)
+            ts.forEachChild(n, walk);
+    };
+    walk(loop.statement);
+    return found;
+}
+function mentionsCursor(node) {
+    let found = false;
+    const walk = (n) => {
+        if (found)
+            return;
+        if (ts.isIdentifier(n) && PAGE_CURSOR.test(n.text))
+            found = true;
+        else
+            ts.forEachChild(n, walk);
+    };
+    walk(node);
+    return found;
+}
+/** `if (ref.length > cap) throw ...` */
+function isThrowingSizeCap(ref) {
+    const access = ref.parent;
+    if (!ts.isPropertyAccessExpression(access) || access.name.text !== 'length')
+        return false;
+    const comparison = access.parent;
+    if (!ts.isBinaryExpression(comparison))
+        return false;
+    const op = comparison.operatorToken.kind;
+    if (op !== ts.SyntaxKind.GreaterThanToken && op !== ts.SyntaxKind.GreaterThanEqualsToken)
+        return false;
+    const statement = comparison.parent;
+    return ts.isIfStatement(statement) && statement.expression === comparison && throwsDirectly(statement.thenStatement);
+}
+function throwsDirectly(statement) {
+    if (ts.isThrowStatement(statement))
+        return true;
+    return ts.isBlock(statement) && statement.statements.some(s => ts.isThrowStatement(s));
+}
+/** `ref.length`, `ref.reduce(...)`, `ref.filter(...).length`, `new Set(ref).size`. */
+function isAggregateUse(ref) {
+    const access = ref.parent;
+    if (ts.isNewExpression(access) && ts.isIdentifier(access.expression) && access.expression.text === 'Set') {
+        const size = access.parent;
+        return ts.isPropertyAccessExpression(size) && size.name.text === 'size';
+    }
+    if (!ts.isPropertyAccessExpression(access) || access.expression !== ref)
+        return false;
+    if (AGGREGATE_METHODS.has(access.name.text))
+        return true;
+    if (access.name.text === 'filter' && ts.isCallExpression(access.parent)) {
+        const after = access.parent.parent;
+        return ts.isPropertyAccessExpression(after) && after.name.text === 'length';
+    }
+    return false;
+}

package/dist/semantic/summaries.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Per-function facts, computed once and reused by every caller.
+ *
+ * Rules decide what a fact is (for example "parameter 2 reaches a fetch that
+ * may follow redirects"); this store only memoizes them and breaks recursion:
+ * a function whose fact is being computed further up the stack answers with
+ * the rule's empty value, which never produces a finding.
+ */
+import type ts from 'typescript';
+import type { FunctionLike } from './ast.js';
+export declare class Summaries {
+    readonly checker: ts.TypeChecker;
+    private readonly values;
+    private readonly active;
+    constructor(checker: ts.TypeChecker);
+    memo<T>(kind: string, fn: FunctionLike, empty: T, compute: () => T): T;
+    private table;
+}

package/dist/semantic/summaries.js

@@ -0,0 +1,33 @@
+export class Summaries {
+    checker;
+    values = new Map();
+    active = new Map();
+    constructor(checker) {
+        this.checker = checker;
+    }
+    memo(kind, fn, empty, compute) {
+        const byFn = this.table(this.values, kind, () => new WeakMap());
+        if (byFn.has(fn))
+            return byFn.get(fn);
+        const running = this.table(this.active, kind, () => new Set());
+        if (running.has(fn))
+            return empty;
+        running.add(fn);
+        try {
+            const value = compute();
+            byFn.set(fn, value);
+            return value;
+        }
+        finally {
+            running.delete(fn);
+        }
+    }
+    table(map, kind, create) {
+        let entry = map.get(kind);
+        if (!entry) {
+            entry = create();
+            map.set(kind, entry);
+        }
+        return entry;
+    }
+}

package/dist/semantic/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Semantic engine types.
+ *
+ * A semantic rule reports a defect only when it can show how it happens:
+ * the line where the risky value enters and the line where it does harm.
+ * Anything the engine cannot resolve produces no finding.
+ */
+import type ts from 'typescript';
+import type { Provenance, Severity } from '../types/index.js';
+import type { Summaries } from './summaries.js';
+export interface SemanticFinding {
+    rule: string;
+    severity: Severity;
+    provenance: Provenance;
+    /** cwd-relative posix path of the reported line. */
+    file: string;
+    line: number;
+    message: string;
+    hint: string;
+    /** Supporting locations, e.g. "http.ts:51 deps.fetch(url, init)". */
+    evidence: string[];
+}
+export interface RuleContext {
+    cwd: string;
+    checker: ts.TypeChecker;
+    sourceFile: ts.SourceFile;
+    summaries: Summaries;
+}
+export interface SemanticRule {
+    id: string;
+    check(ctx: RuleContext): SemanticFinding[];
+}

package/dist/semantic/types.js

@@ -0,0 +1 @@
+export {};

package/dist/storage/index.d.ts

@@ -16,4 +16,5 @@ export type { ApplicableLessons, InteractionEvidence, LessonRecord, LessonState,
 export { queueLocalLessonsForTeam } from './team-import.js';
 export type { LocalLessonImportOptions, LocalLessonImportResult } from './team-import.js';
 export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, } from './team-store.js';
+export { explainTeamConnectionError } from './team-diagnostics.js';
 export type { TeamConfiguration, TeamSemanticConfiguration, TeamModeStatus, TeamDoctorResult, SemanticKnowledgeCandidate, SemanticKnowledgeResult, } from './team-store.js';

package/dist/storage/index.js

@@ -11,3 +11,4 @@ export { recordContextEvent, recordModelUsage, setContextCacheRecord, getContext
 export { recordInteractionEvidence, countInteractionEvidence, recordInteractionLesson, listLessons, listKnowledgeLessons, getApplicableLessons, transitionLesson, getRepositoryId } from './lessons.js';
 export { queueLocalLessonsForTeam } from './team-import.js';
 export { loadTeamConfiguration, saveTeamConfiguration, initializeTeamSchema, getTeamModeStatus, doctorTeamConnection, syncTeamOutbox, searchTeamKnowledge, backfillTeamEmbeddings, TEAM_CONFIG_PATH, validateTeamDatabaseUrl, } from './team-store.js';
+export { explainTeamConnectionError } from './team-diagnostics.js';

package/dist/storage/team-diagnostics.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Turns team-database failures into messages that say what to do.
+ *
+ * `team doctor` used to throw "Database role is not provisioned for this
+ * team" whenever the membership query returned no row, including when the
+ * role was provisioned but row-level security hid it, and let connection
+ * errors escape as stack traces.
+ */
+export interface QueryablePool {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: any[];
+        rowCount: number | null;
+    }>;
+}
+/** A connection or query error, explained with the fix. */
+export declare function explainTeamConnectionError(error: unknown): string;
+/**
+ * Why the membership query returned no row: RLS without a policy for this
+ * login, or no membership row for it. Visibility is read from the catalog,
+ * which every login can see.
+ */
+export declare function diagnoseMissingMembership(pool: QueryablePool): Promise<string>;

package/dist/storage/team-diagnostics.js

@@ -0,0 +1,58 @@
+/**
+ * Turns team-database failures into messages that say what to do.
+ *
+ * `team doctor` used to throw "Database role is not provisioned for this
+ * team" whenever the membership query returned no row, including when the
+ * role was provisioned but row-level security hid it, and let connection
+ * errors escape as stack traces.
+ */
+const UNTRUSTED_CERTIFICATE = new Set([
+    'SELF_SIGNED_CERT_IN_CHAIN',
+    'DEPTH_ZERO_SELF_SIGNED_CERT',
+    'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+    'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+]);
+/** A connection or query error, explained with the fix. */
+export function explainTeamConnectionError(error) {
+    const err = error;
+    const code = err?.code ?? '';
+    const detail = err?.message ?? String(error);
+    if (UNTRUSTED_CERTIFICATE.has(code)) {
+        return `TLS: the database certificate chain is not trusted by Node (${code}). Managed hosts such as Supabase sign `
+            + `with their own root CA: download it from the provider, set NODE_EXTRA_CA_CERTS=<path to the CA file>, and keep sslmode=verify-full.`;
+    }
+    if (code === 'ENOTFOUND' || code === 'ECONNREFUSED' || code === 'ETIMEDOUT' || code === 'EHOSTUNREACH') {
+        return `Cannot reach the team database (${code}): check the host, port and network access. ${detail}`;
+    }
+    if (code === '28P01' || code === '28000') {
+        return `The database rejected the login (${code}): check the user and password in the team database URL.`;
+    }
+    if (code === '3F000' || code === '42P01') {
+        return `The team schema is missing (${code}): run \`rigour team init-schema\` with the administrator URL.`;
+    }
+    return detail;
+}
+/**
+ * Why the membership query returned no row: RLS without a policy for this
+ * login, or no membership row for it. Visibility is read from the catalog,
+ * which every login can see.
+ */
+export async function diagnoseMissingMembership(pool) {
+    let hidden = [];
+    try {
+        const result = await pool.query(`SELECT c.relname AS table_name
+               FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+              WHERE n.nspname = 'rigour' AND c.relname IN ('memberships', 'meta') AND c.relrowsecurity
+                AND NOT EXISTS (SELECT 1 FROM pg_policies p WHERE p.schemaname = 'rigour' AND p.tablename = c.relname)`);
+        hidden = result.rows.map(row => String(row.table_name));
+    }
+    catch {
+        // Catalog not readable: fall back to the provisioning message.
+    }
+    if (hidden.length > 0) {
+        return `Row-level security is enabled on ${hidden.map(t => `rigour.${t}`).join(' and ')} with no policy, so this login `
+            + `cannot see its membership. Run \`rigour team init-schema\` with the administrator URL to add the read policies.`;
+    }
+    return 'This database role has no membership for the configured organization, team and actor. '
+        + 'Ask the administrator to add it (see docs/ENTERPRISE.md).';
+}

package/dist/storage/team-diagnostics.test.d.ts

@@ -0,0 +1 @@
+export {};