@seanhogg/builderforce-memory 2026.10.28 → 2026.10.29

package/dist/knowledge/model.d.ts

@@ -0,0 +1,333 @@
+/**
+ * The knowledge graph model — memory's structure for KNOWLEDGE: facts connected to each
+ * other and to the sources they came from (PRD: Builderforce.ai/docs/specs/38-prd-knowledge-graph.md).
+ *
+ * Generic: it knows sources, entities, facts and relations — never imports or headings.
+ * Packs (docs builtin, code registered by the host) supply that meaning as DATA.
+ *
+ * Store judgement, compute perception: `extracted` nodes/edges are recomputed from sources
+ * (cached by content hash) and are NEVER written to a KnowledgeStore; `model`/`human`/`agent`
+ * ones are stored with the content hash they were judged from and go stale when it changes.
+ */
+import type { IngestManifest, SourceDocument, ParsedSection } from '../ingest/types.js';
+import type { IndexDoc, SimilarPair } from '../retrieval/knowledge-index/types.js';
+/** `src:${rootId}::${path}` · `ent:${pack}:${normalizedName}` · `fact:${key}` (claims are `fact:claim:${hash}`). */
+export type NodeRef = `src:${string}` | `ent:${string}` | `fact:${string}`;
+export type Origin = 'extracted' | 'model' | 'human' | 'agent';
+export type StoredOrigin = Exclude<Origin, 'extracted'>;
+export interface KNode {
+    ref: NodeRef;
+    /** Pack-defined: 'file' | 'section' | 'symbol' | 'area' | 'entity' | 'claim' | 'fact' … */
+    kind: string;
+    label: string;
+    pack: string;
+    partition?: string;
+    area?: NodeRef;
+    /** PageRank over the joined graph, normalized 0–1 (areas: sum of members, renormalized). */
+    importance: number;
+    origin: Origin;
+    sourceHash?: string;
+    stale?: boolean;
+    /** Pack data, e.g. { added, removed }, { unused: 'file' }, { line: 12 }. */
+    badges?: Record<string, number | string>;
+}
+export type EdgeVerdict = 'allowed' | 'same' | 'skips' | 'upward';
+export interface KEdge {
+    from: NodeRef;
+    to: NodeRef;
+    /** 'references' | 'links' | 'contains' | 'mentions' | 'duplicate' | 'near-duplicate'
+     *  | 'contradicts' | 'agrees' | 'supersedes' | 'about' | 'co-changed' — a new kind is a value. */
+    kind: string;
+    weight: number;
+    origin: Origin;
+    confidence?: number;
+    verdict?: EdgeVerdict;
+    cycle?: boolean;
+}
+/** Output of a pack's deterministic extractor (or analyzer) for one source. Never stored. */
+export interface Extracted {
+    sourceRef: NodeRef;
+    sourceHash: string;
+    nodes: KNode[];
+    edges: KEdge[];
+    /** Exact keys for entity resolution and the index's exact tier. */
+    keys: Array<{
+        ref: NodeRef;
+        key: string;
+    }>;
+}
+export interface ExtractContext {
+    rootId: string;
+    /** Normalized entity keys known so far (for `mentions`). */
+    knownKeys: ReadonlyMap<string, NodeRef>;
+    /** Resolves a relative link/import from `fromPath` to a root-relative path, or undefined. */
+    resolvePath(fromPath: string, target: string): string | undefined;
+}
+/** A finding a person can act on. `kind` is pack-defined; `requestKey` names an i18n template. */
+export interface Finding {
+    id: string;
+    kind: string;
+    pack: string;
+    nodes: NodeRef[];
+    severity: 'info' | 'warn' | 'error';
+    /** Numbers/strings for the label and the Fix-with-agent template. */
+    params: Record<string, string | number>;
+    /** i18n key of the fixed Fix-with-agent request (e.g. 'knowledgeGraph.fix.cloneGroup'). */
+    requestKey?: string;
+}
+export interface FindingRule {
+    id: string;
+    find(graph: KnowledgeGraph): Finding[];
+}
+export interface PartitionRule {
+    id: string;
+    /** 0 = top. */
+    order: number;
+    /** Globs over the source path; first matching rule wins. */
+    match: string[];
+}
+export interface PartitionRegistry {
+    partitions: PartitionRule[];
+    /** from-partition → partitions it may use. Absent ⇒ no verdicts. */
+    allow?: Record<string, string[]>;
+}
+/** What the judgement model is asked for one section kind; output is schema-validated. */
+export interface JudgementSpec {
+    /** Node kinds whose text is judged (e.g. ['section']). */
+    nodeKinds: string[];
+    /** Ask for claims[] / entities[] per node; and contradicts|agrees for near-duplicate claim pairs. */
+    claims: boolean;
+    entities: boolean;
+    contradictions: boolean;
+}
+export interface JudgementRequest {
+    kind: 'extract' | 'compare';
+    /** extract: one node's text; compare: two claims. */
+    items: Array<{
+        ref: NodeRef;
+        text: string;
+        sourceHash: string;
+    }>;
+    signal?: AbortSignal;
+}
+export interface JudgedClaim {
+    subject: string;
+    predicate: string;
+    object: string;
+    quote: string;
+}
+export interface JudgedEntity {
+    name: string;
+    type: string;
+}
+export interface JudgementResult {
+    extract?: Array<{
+        ref: NodeRef;
+        claims: JudgedClaim[];
+        entities: JudgedEntity[];
+    }>;
+    compare?: Array<{
+        a: NodeRef;
+        b: NodeRef;
+        relation: 'contradicts' | 'agrees' | 'unrelated';
+        confidence: number;
+    }>;
+    /** Items dropped for invalid output. */
+    invalid: number;
+}
+/** A routed model call. Hosts implement it (VS Code/on-prem: local engines → gateway; web: POST …/knowledge/judge). */
+export interface JudgementPort {
+    judge(req: JudgementRequest): Promise<JudgementResult>;
+}
+/** Host-run tools for a pack (code: dependency-cruiser/jscpd/knip). Returns extra extracted edges/badges. */
+export interface AnalyzerPort {
+    analyse(rootId: string, signal?: AbortSignal): Promise<Extracted[]>;
+}
+/** A host-supplied parser that also extracts graph structure. `extract` is the optional ingest extension. */
+export interface KnowledgeParser {
+    id: string;
+    accepts(source: SourceDocument): boolean;
+    parse(source: SourceDocument): ParsedSection[];
+    extract?(source: SourceDocument, sections: ParsedSection[], ctx: ExtractContext): Extracted;
+}
+export interface KnowledgePack {
+    /** 'docs' | 'code' */
+    id: string;
+    parsers: KnowledgeParser[];
+    partitions?: PartitionRegistry;
+    findings?: FindingRule[];
+    judgement?: JudgementSpec;
+    analyzers?: AnalyzerPort;
+}
+export interface StoredFact {
+    /** project_facts.key — judgement nodes use `ent:<pack>:<name>` / `claim:<hash>` namespaces. */
+    key: string;
+    content: string;
+    source: string;
+    importance: number;
+    origin: StoredOrigin;
+    fileAnchors: Array<{
+        path: string;
+        line?: number;
+        contentHash?: string;
+    }>;
+    updatedAt?: string;
+    createdBy?: number | null;
+}
+export interface StoredRelation {
+    from: NodeRef;
+    to: NodeRef;
+    kind: string;
+    weight: number;
+    origin: StoredOrigin;
+    confidence?: number;
+    sourceHash?: string;
+    staleAt?: string | null;
+}
+export interface Scope {
+    rootId: string;
+}
+export interface ScopeRecord {
+    rootId: string;
+    title: string;
+    packs: string[];
+    lastDigest?: string;
+    lastReviewedAt?: string;
+}
+/** Where knowledge is persisted: the platform API adapter or the local snapshot adapter. */
+export interface KnowledgeStore {
+    scopes(): Promise<ScopeRecord[]>;
+    facts(scope: Scope): Promise<StoredFact[]>;
+    relations(scope: Scope): Promise<StoredRelation[]>;
+    write(batch: {
+        scope: ScopeRecord;
+        facts: StoredFact[];
+        relations: StoredRelation[];
+    }): Promise<void>;
+    /** Marks model facts/relations judged from `sourceRef` at a hash other than `currentHash` stale. */
+    markStale(scope: Scope, sourceRef: NodeRef, currentHash: string): Promise<void>;
+    /** Extracted output cache, by content hash (never knowledge — perception). */
+    getExtracted?(hash: string): Promise<Extracted[] | undefined>;
+    putExtracted?(hash: string, extracted: Extracted[]): Promise<void>;
+}
+/** Where files come from: one adapter per host. */
+export interface DirectorySource {
+    rootId: string;
+    title: string;
+    list(): AsyncIterable<{
+        path: string;
+        hash: string;
+        size: number;
+    }>;
+    read(path: string): Promise<SourceDocument>;
+    watch?(cb: (paths: string[]) => void): () => void;
+}
+export interface LiveOverlay {
+    changes: Array<{
+        path: string;
+        status: string;
+        added: number;
+        removed: number;
+    }>;
+    /** Files touched together in one run → co-changed edges. */
+    runFiles?: string[];
+}
+export interface KnowledgeGraph {
+    scope: {
+        rootId: string;
+        packs: string[];
+        digest: string;
+    };
+    nodes: KNode[];
+    edges: KEdge[];
+    findings: Finding[];
+    stats: {
+        sources: number;
+        nodes: number;
+        edges: number;
+        stale: number;
+        truncated: boolean;
+    };
+}
+export interface ReviewPlan {
+    rootId: string;
+    files: number;
+    byPack: Record<string, number>;
+    unchanged: number;
+    changed: string[];
+    removed: string[];
+    skipped: Array<{
+        path: string;
+        reason: 'ignored' | 'binary' | 'too-large' | 'no-pack';
+    }>;
+    /** ≈ judgement calls for changed files (sections of judged kinds). */
+    estimatedModelCalls: number;
+}
+export interface ReviewProgress {
+    phase: 'plan' | 'extract' | 'resolve' | 'judge' | 'write' | 'index' | 'done';
+    done: number;
+    total: number;
+    path?: string;
+}
+export interface ReviewReport {
+    rootId: string;
+    digest: string;
+    extracted: number;
+    judged: number;
+    /** Sections left extracted-only because the budget ran out. */
+    unjudged: number;
+    invalidJudgements: number;
+    factsWritten: number;
+    relationsWritten: number;
+    staleMarked: number;
+    aborted: boolean;
+    durationMs: number;
+}
+export interface ReviewArgs {
+    source: DirectorySource;
+    store: KnowledgeStore;
+    packs: KnowledgePack[];
+    manifest: IngestManifest;
+    judgement?: JudgementPort;
+    /** Near-duplicate claim pairs to compare / possible-same entities; from the knowledge index. */
+    similar?: (ids: string[]) => Promise<SimilarPair[]>;
+    budget: {
+        modelCalls: number;
+        ms: number;
+    };
+    signal?: AbortSignal;
+    onProgress?(p: ReviewProgress): void;
+}
+export interface BuildGraphInput {
+    rootId: string;
+    extracted: Extracted[];
+    facts: StoredFact[];
+    relations: StoredRelation[];
+    packs: KnowledgePack[];
+    live?: LiveOverlay;
+    nearDuplicates?: SimilarPair[];
+}
+export interface BuildGraphOptions {
+    /** Default 400; cap 2000. */
+    maxNodes?: number;
+    focus?: NodeRef[];
+}
+export interface TraceStep {
+    from: NodeRef;
+    to: NodeRef;
+    depth: number;
+    kind: string;
+    verdict?: EdgeVerdict;
+    cycle?: boolean;
+    back?: boolean;
+}
+export interface Trace {
+    from: NodeRef;
+    /** Partitions present, in registry order (lanes). */
+    lanes: string[];
+    steps: TraceStep[];
+    truncated: boolean;
+}
+/** Re-exported for card consumers. */
+export type { IndexDoc };
+//# sourceMappingURL=model.d.ts.map

package/dist/knowledge/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/knowledge/model.ts"],"names":[],"mappings":"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"}

package/dist/knowledge/model.js

@@ -0,0 +1,13 @@
+/**
+ * The knowledge graph model — memory's structure for KNOWLEDGE: facts connected to each
+ * other and to the sources they came from (PRD: Builderforce.ai/docs/specs/38-prd-knowledge-graph.md).
+ *
+ * Generic: it knows sources, entities, facts and relations — never imports or headings.
+ * Packs (docs builtin, code registered by the host) supply that meaning as DATA.
+ *
+ * Store judgement, compute perception: `extracted` nodes/edges are recomputed from sources
+ * (cached by content hash) and are NEVER written to a KnowledgeStore; `model`/`human`/`agent`
+ * ones are stored with the content hash they were judged from and go stale when it changes.
+ */
+export {};
+//# sourceMappingURL=model.js.map

package/dist/knowledge/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/knowledge/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/knowledge/packs/docs.d.ts

@@ -0,0 +1,17 @@
+/**
+ * knowledge/packs/docs.ts — the docs pack, built into memory (PRD 38 §4.5).
+ *
+ * Parsers are the ONE builtin ingest parsers (markdown, HTML, plain text); their `extract`
+ * lives in `ingest/docsExtract.ts`. Partitions: one plane per top-level folder, no `allow`
+ * (so no verdicts). Findings: broken links and orphan documents. Judgement: claims,
+ * entities and contradictions per section.
+ */
+import { DOCS_PACK_ID } from '../../ingest/docsExtract.js';
+import type { FindingRule, KnowledgePack } from '../model.js';
+export { DOCS_PACK_ID };
+/** Links to documents that are not in the directory, grouped per linking file. */
+export declare const brokenLinkRule: FindingRule;
+/** Documents no other document links to (entry documents aside), as one finding. */
+export declare const orphanDocumentRule: FindingRule;
+export declare const DOCS_PACK: KnowledgePack;
+//# sourceMappingURL=docs.d.ts.map

package/dist/knowledge/packs/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../../../src/knowledge/packs/docs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAW,WAAW,EAAkB,aAAa,EAAW,MAAM,aAAa,CAAC;AAKhG,OAAO,EAAE,YAAY,EAAE,CAAC;AAWxB,kFAAkF;AAClF,eAAO,MAAM,cAAc,EAAE,WAyB5B,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,EAAE,WAqBhC,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,aAWvB,CAAC"}

package/dist/knowledge/packs/docs.js

@@ -0,0 +1,89 @@
+/**
+ * knowledge/packs/docs.ts — the docs pack, built into memory (PRD 38 §4.5).
+ *
+ * Parsers are the ONE builtin ingest parsers (markdown, HTML, plain text); their `extract`
+ * lives in `ingest/docsExtract.ts`. Partitions: one plane per top-level folder, no `allow`
+ * (so no verdicts). Findings: broken links and orphan documents. Judgement: claims,
+ * entities and contradictions per section.
+ */
+import { htmlParser, markdownParser, plainTextParser } from '../../ingest/parsers.js';
+import { DOCS_PACK_ID } from '../../ingest/docsExtract.js';
+import { findingId, MAX_FINDING_NODES, requestKeyFor } from '../findings.js';
+import { TOP_LEVEL_FOLDER } from '../partitions.js';
+import { basenameOf, compareStr, fileRefOf, pathOfRef } from '../refs.js';
+export { DOCS_PACK_ID };
+/** Targets with these extensions (or none) are documents; a link to anything else is not judged broken. */
+const DOC_TARGET = /(?:\.(?:md|markdown|mdx|html?|txt|rst|adoc)|\/[^./]*|^[^./]*)$/i;
+/** Entry documents are expected to have no inbound links. */
+const ENTRY_DOC = /^(readme|index|home|_index|summary)\.[a-z]+$/i;
+function fileOf(g) {
+    return new Map(g.nodes.map((n) => [n.ref, fileRefOf(n.ref)]));
+}
+/** Links to documents that are not in the directory, grouped per linking file. */
+export const brokenLinkRule = {
+    id: 'docs.broken-link',
+    find(g) {
+        const kind = new Map(g.nodes.map((n) => [n.ref, n.kind]));
+        const file = fileOf(g);
+        const bySource = new Map();
+        for (const e of g.edges) {
+            if (e.kind !== 'links' || kind.get(e.to) !== 'missing')
+                continue;
+            if (!DOC_TARGET.test(pathOfRef(e.to) ?? ''))
+                continue;
+            const source = file.get(e.from) ?? e.from;
+            const list = bySource.get(source) ?? [];
+            list.push(e.to);
+            bySource.set(source, list);
+        }
+        return [...bySource].sort((a, b) => compareStr(a[0], b[0])).map(([source, targets]) => {
+            const unique = [...new Set(targets)].sort(compareStr);
+            const nodes = [source, ...unique];
+            return {
+                id: findingId('broken-link', nodes), kind: 'broken-link', pack: DOCS_PACK_ID,
+                nodes: nodes.slice(0, MAX_FINDING_NODES), severity: 'warn',
+                params: { count: unique.length, file: pathOfRef(source) ?? source },
+                requestKey: requestKeyFor('broken-link'),
+            };
+        });
+    },
+};
+/** Documents no other document links to (entry documents aside), as one finding. */
+export const orphanDocumentRule = {
+    id: 'docs.orphan',
+    find(g) {
+        const file = fileOf(g);
+        const linked = new Set();
+        for (const e of g.edges) {
+            if (e.kind !== 'links')
+                continue;
+            const from = file.get(e.from) ?? e.from, to = file.get(e.to) ?? e.to;
+            if (from !== to)
+                linked.add(to);
+        }
+        const orphans = g.nodes
+            .filter((n) => n.pack === DOCS_PACK_ID && n.kind === 'file' && !linked.has(n.ref))
+            .filter((n) => !ENTRY_DOC.test(basenameOf(pathOfRef(n.ref) ?? '')))
+            .map((n) => n.ref).sort(compareStr);
+        if (orphans.length === 0)
+            return [];
+        return [{
+                id: findingId('orphan', orphans), kind: 'orphan', pack: DOCS_PACK_ID,
+                nodes: orphans.slice(0, MAX_FINDING_NODES), severity: 'info',
+                params: { count: orphans.length }, requestKey: requestKeyFor('orphan'),
+            }];
+    },
+};
+export const DOCS_PACK = {
+    id: DOCS_PACK_ID,
+    parsers: [markdownParser, htmlParser, plainTextParser],
+    partitions: {
+        partitions: [
+            { id: TOP_LEVEL_FOLDER, order: 0, match: ['*/**'] },
+            { id: '(root)', order: 0, match: ['*'] },
+        ],
+    },
+    findings: [brokenLinkRule, orphanDocumentRule],
+    judgement: { nodeKinds: ['section'], claims: true, entities: true, contradictions: true },
+};
+//# sourceMappingURL=docs.js.map

package/dist/knowledge/packs/docs.js.map

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

package/dist/knowledge/partitions.d.ts

@@ -0,0 +1,31 @@
+/**
+ * knowledge/partitions.ts — ordered groups of sources and who may use whom (PRD 38 §4.4).
+ *
+ * Generic: code layers and doc folders are both a {@link PartitionRegistry}. An edge's
+ * verdict is `same`, `allowed`, `upward` (to a lower order, i.e. a layer above) or
+ * `skips` (anything else), and is set only when the registry defines `allow` and both
+ * ends are partitioned.
+ *
+ * A rule whose id is {@link TOP_LEVEL_FOLDER} names its partition after the path's first
+ * folder — the docs pack's "one plane per top-level folder" with no per-folder rows.
+ */
+import type { EdgeVerdict, KnowledgePack, PartitionRegistry } from './model.js';
+/** Rule id meaning "the matched path's top-level folder". */
+export declare const TOP_LEVEL_FOLDER = "*";
+/**
+ * A glob as a RegExp over `/`-separated paths: `**` spans folders (`**\/` may match none),
+ * `*` and `?` stay within one segment, `{a,b}` is alternation.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+export declare function matchGlob(path: string, glob: string): boolean;
+/** The partition a root-relative path belongs to: the first matching rule, in registry order. */
+export declare function partitionOf(path: string, reg: PartitionRegistry): string | undefined;
+/** The order of a partition (folder partitions from {@link TOP_LEVEL_FOLDER} share that rule's). */
+export declare function partitionOrder(id: string, reg: PartitionRegistry): number | undefined;
+export declare function verdictOf(from: string | undefined, to: string | undefined, reg: PartitionRegistry): EdgeVerdict | undefined;
+/**
+ * A pack's registry, or a validated `.builderforce/partitions.json` override. Throws a
+ * `TypeError` naming the first problem when the override is not a {@link PartitionRegistry}.
+ */
+export declare function loadPartitions(pack: KnowledgePack, override?: unknown): PartitionRegistry;
+//# sourceMappingURL=partitions.d.ts.map

package/dist/knowledge/partitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partitions.d.ts","sourceRoot":"","sources":["../../src/knowledge/partitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAiB,MAAM,YAAY,CAAC;AAE/F,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAIpC;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBjD;AAMD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAE7D;AAED,iGAAiG;AACjG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAQpF;AAED,oGAAoG;AACpG,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAGrF;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,iBAAiB,GAAG,WAAW,GAAG,SAAS,CAQ3H;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,iBAAiB,CA+BzF"}

package/dist/knowledge/partitions.js

@@ -0,0 +1,135 @@
+/**
+ * knowledge/partitions.ts — ordered groups of sources and who may use whom (PRD 38 §4.4).
+ *
+ * Generic: code layers and doc folders are both a {@link PartitionRegistry}. An edge's
+ * verdict is `same`, `allowed`, `upward` (to a lower order, i.e. a layer above) or
+ * `skips` (anything else), and is set only when the registry defines `allow` and both
+ * ends are partitioned.
+ *
+ * A rule whose id is {@link TOP_LEVEL_FOLDER} names its partition after the path's first
+ * folder — the docs pack's "one plane per top-level folder" with no per-folder rows.
+ */
+/** Rule id meaning "the matched path's top-level folder". */
+export const TOP_LEVEL_FOLDER = '*';
+const globCache = new Map();
+/**
+ * A glob as a RegExp over `/`-separated paths: `**` spans folders (`**\/` may match none),
+ * `*` and `?` stay within one segment, `{a,b}` is alternation.
+ */
+export function globToRegExp(glob) {
+    const cached = globCache.get(glob);
+    if (cached)
+        return cached;
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === '*') {
+            if (glob[i + 1] === '*') {
+                const slashAfter = glob[i + 2] === '/';
+                re += slashAfter ? '(?:.*/)?' : '.*';
+                i += slashAfter ? 2 : 1;
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (ch === '?')
+            re += '[^/]';
+        else if (ch === '{') {
+            const close = glob.indexOf('}', i);
+            if (close < 0) {
+                re += '\\{';
+                continue;
+            }
+            re += `(?:${glob.slice(i + 1, close).split(',').map(escapeRe).join('|')})`;
+            i = close;
+        }
+        else
+            re += escapeRe(ch);
+    }
+    const compiled = new RegExp(`^${re}$`);
+    globCache.set(glob, compiled);
+    return compiled;
+}
+function escapeRe(s) {
+    return s.replace(/[.+^${}()|[\]\\*?]/g, '\\$&');
+}
+export function matchGlob(path, glob) {
+    return globToRegExp(glob).test(path);
+}
+/** The partition a root-relative path belongs to: the first matching rule, in registry order. */
+export function partitionOf(path, reg) {
+    for (const rule of reg.partitions) {
+        if (!rule.match.some((g) => matchGlob(path, g)))
+            continue;
+        if (rule.id !== TOP_LEVEL_FOLDER)
+            return rule.id;
+        const slash = path.indexOf('/');
+        return slash > 0 ? path.slice(0, slash) : undefined;
+    }
+    return undefined;
+}
+/** The order of a partition (folder partitions from {@link TOP_LEVEL_FOLDER} share that rule's). */
+export function partitionOrder(id, reg) {
+    const rule = reg.partitions.find((r) => r.id === id) ?? reg.partitions.find((r) => r.id === TOP_LEVEL_FOLDER);
+    return rule?.order;
+}
+export function verdictOf(from, to, reg) {
+    if (!reg.allow || from === undefined || to === undefined)
+        return undefined;
+    if (from === to)
+        return 'same';
+    if (reg.allow[from]?.includes(to))
+        return 'allowed';
+    const fromOrder = partitionOrder(from, reg);
+    const toOrder = partitionOrder(to, reg);
+    if (fromOrder !== undefined && toOrder !== undefined && toOrder < fromOrder)
+        return 'upward';
+    return 'skips';
+}
+/**
+ * A pack's registry, or a validated `.builderforce/partitions.json` override. Throws a
+ * `TypeError` naming the first problem when the override is not a {@link PartitionRegistry}.
+ */
+export function loadPartitions(pack, override) {
+    if (override === undefined || override === null)
+        return pack.partitions ?? { partitions: [] };
+    const fail = (why) => { throw new TypeError(`partitions.json: ${why}`); };
+    if (typeof override !== 'object' || Array.isArray(override))
+        fail('expected an object');
+    const o = override;
+    if (!Array.isArray(o['partitions']))
+        fail('`partitions` must be an array');
+    const partitions = o['partitions'].map((raw, i) => {
+        const r = raw;
+        if (!r || typeof r !== 'object')
+            fail(`partitions[${i}] must be an object`);
+        if (typeof r['id'] !== 'string' || !r['id'])
+            fail(`partitions[${i}].id must be a non-empty string`);
+        if (typeof r['order'] !== 'number' || !Number.isFinite(r['order']))
+            fail(`partitions[${i}].order must be a number`);
+        const match = r['match'];
+        if (!Array.isArray(match) || !match.every((g) => typeof g === 'string' && g)) {
+            fail(`partitions[${i}].match must be an array of globs`);
+        }
+        return { id: r['id'], order: r['order'], match: [...match] };
+    });
+    const ids = new Set(partitions.map((p) => p.id));
+    if (ids.size !== partitions.length)
+        fail('partition ids must be unique');
+    if (o['allow'] === undefined)
+        return { partitions };
+    const allowRaw = o['allow'];
+    if (!allowRaw || typeof allowRaw !== 'object' || Array.isArray(allowRaw))
+        fail('`allow` must be an object');
+    const allow = {};
+    for (const [from, to] of Object.entries(allowRaw)) {
+        if (!ids.has(from))
+            fail(`allow.${from} names an unknown partition`);
+        if (!Array.isArray(to) || !to.every((t) => typeof t === 'string' && ids.has(t))) {
+            fail(`allow.${from} must list known partition ids`);
+        }
+        allow[from] = [...to];
+    }
+    return { partitions, allow };
+}
+//# sourceMappingURL=partitions.js.map