@agentskit/doc-bridge 1.7.44 → 1.9.0

package/src/cli/usage.ts

@@ -0,0 +1,71 @@
+/**
+ * The CLI's usage text, in its own module.
+ *
+ * `ak-docs parity` checks that a command this repository documents in public is a command the CLI
+ * actually offers, which means something other than the CLI has to be able to read the usage. The
+ * text lives here so that check does not import the program and create a cycle through it.
+ */
+export const CLI_COMMAND_USAGE = `ak-docs — human↔agent documentation bridge (@agentskit/doc-bridge)
+
+Core (no API key):
+  ak-docs init [--demo] [--scaffold-workspaces]
+  ak-docs demo [--fixture example|monorepo] [--text] [--in-project]
+  ak-docs doctor [--text] [--badge] [--write-badge]
+  ak-docs index [--watch]
+  ak-docs discover [--text|--json]
+  ak-docs benchmark <fixture.json> <observation.json> [--text|--json]
+  ak-docs bench retrieval <suite.json> [--index <file>] [--baseline <file>] [--limit <n>] [--text|--json]
+  ak-docs bench retrieval <suite.json> --update-baseline --by <name> [--reason <text>]
+  ak-docs study protocol <protocol.json> [--text|--json]
+  ak-docs study history <registry.json> [--protocol <protocol.json>] [--text|--json]
+  ak-docs study tasks <task-suite.json> [--text|--json]
+  ak-docs study select <task-suite.json> [--text|--json]
+  ak-docs study plan <run-plan.json> [--text|--json]
+  ak-docs study providers <provider-cli.json> [--text|--json]
+  ak-docs study run <run-plan.json> <task-suite.json> --providers <provider-cli.json> --repositories <repositories.json> --ledger <ledger.json> [--round <id>] [--dry-run] [--text|--json]
+  ak-docs study adjudicate <observation-ledger.json> <task-suite.json> --adjudicator <provider-cli.json> --output <ledger.json> [--run-id <id>] [--offset <n>] [--limit <n>] [--text|--json]
+  ak-docs study ledger <observation-ledger.json> [--text|--json]
+  ak-docs study verification <binding.json> [--text|--json]
+  ak-docs study metrics <observation-ledger.json> [--baseline-round <id>] [--current-round <id>] [--baseline-run-id <id>] [--current-run-id <id>] [--allow-regressions] [--text|--json]
+  ak-docs scan | reconcile | check | map [--text|--json] [--html] [--report-threshold <bytes>]
+  ak-docs check --json --format finding             emit diagnostics in the ecosystem Finding shape
+  ak-docs bench retrieval <suite> --overlay        measure the suite with and without the accepted overlay
+  ak-docs enrich --retrieval-delta                 run the overlay through the golden suite after enriching
+  ak-docs study expectations <suite> --expectations <file>   check the study's mechanical retrieval expectations
+  ak-docs check --enrich          run the enrichment stage between reconcile and evaluate
+  ak-docs enrich [--json|--text]  run the configured Registry roles over context packs
+  ak-docs enrich list | approve <proposalId> --by <name> | reject <proposalId> --by <name> [--reason <text>]
+  ak-docs fix propose links|normalize <artifact> [--output <file>]
+  ak-docs fix approve|apply <proposal.json> [--by <name>]
+  ak-docs suggest [--documentation] [--json|--text]   run the configured Registry agent
+  ak-docs query [package|ownership|intent|change] <id> [--agent] [--text]
+  ak-docs search <term> [--agent] [--explain] [--mode=<mode>] [--context-budget=<tokens>] [--text]
+  ak-docs list <packages|intents|changes|knowledge> [--text]
+  ak-docs ask [question]          local consult (no LLM)
+  ak-docs gate run [gate-id]
+  ak-docs rules run <report.json> [--preset default|recommended|strict] [--severity rule=level] [--ignore rule]
+  ak-docs conformance run documentation-standard-v1 [--text|--json]
+  ak-docs audit documentation [--text|--json]
+  ak-docs parity [--claims <file>] [--json|--text]   check public claims against what the repository proves
+  ak-docs render <llms.txt|area|ownership|change-digest|overlay-review> [--data <artifact>] [--output <path>] [--print-template] [--json]
+  ak-docs mcp
+  ak-docs mcp install --cursor | --claude
+  ak-docs memory ingest|classify|promote [--pr] [--dry-run]
+  ak-docs bootstrap agent-docs
+  ak-docs validate-config | validate-handoff <file>
+
+Intelligence (optional AgentsKit peers):
+  ak-docs rag ingest|search <query>
+  ak-docs chat                    terminal chat (Ink + RAG)
+  ak-docs ask <question> --chat   one-shot grounded answer
+
+Advanced / ecosystem:
+  ak-docs retrieve <query>
+  ak-docs registry topology
+  ak-docs playbook draft | pattern [--text]
+
+Global flags:
+  -h, --help   --version
+  --config <path>   (project root = config file directory)
+  --agent   --json   --text   --chat   --demo
+`

package/src/config/defaults.ts

@@ -57,6 +57,7 @@ export const applyConfigDefaults = (config: DocBridgeConfigV1): DocBridgeConfigV
           'memory.classify', 'memory.promoteDraft', 'registry.topology',
           'docbridge.snapshot', 'docbridge.report', 'docbridge.diagnostics',
           'docbridge.relations', 'docbridge.run', 'docbridge.proposals',
+          'knowledge.search', 'knowledge.lookup',
         ],
         transport: 'stdio',
         ...config.surfaces?.mcp,

package/src/config/index.ts

@@ -8,6 +8,7 @@ export {
 } from './load-config.js'
 export {
   DocBridgeConfigV1Schema,
+  DocumentationAuditConfigSchema,
   ReconciliationConfigSchema,
   AgentCorpusConfigSchema,
   HumanCorpusConfigSchema,
@@ -16,10 +17,13 @@ export {
   EcosystemContractEvidenceSchema,
   ConformanceConfigSchema,
   ReportConfigSchema,
+  RetrievalConfigSchema,
   type DocBridgeConfigV1,
+  type DocumentationAuditConfig,
   type AgentCorpusConfig,
   type DocumentationStandardRuleId,
   type DocumentationStandardV1Config,
   type ReconciliationConfig,
   type ReportConfig,
+  type RetrievalConfig,
 } from './schema.js'

package/src/config/load-config.ts

@@ -79,7 +79,13 @@ const parseConfig = (input: unknown): DocBridgeConfigV1 => {
   if (result.success) return result.data
   throw new Error(
     `Invalid doc-bridge config:\n${result.error.issues.map((issue) =>
-      `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`,
+      `  - ${issue.path.join('.') || '(root)'}: ${
+        issue.code === 'invalid_type' && issue.message.endsWith('received undefined')
+          ? 'Required'
+          : issue.code === 'invalid_value' && 'values' in issue
+            ? 'Invalid enum value'
+            : issue.message
+      }`,
     ).join('\n')}`,
   )
 }

package/src/config/schema.ts

@@ -171,24 +171,47 @@ export const RuleSeveritySchema = z.enum(['off', 'info', 'warn', 'error'])
 export const RulesConfigSchema = z
   .object({
     mode: z.enum(['default', 'recommended', 'strict']).optional(),
-    severity: z.record(RuleIdSchema, RuleSeveritySchema).optional(),
+    severity: z.partialRecord(RuleIdSchema, RuleSeveritySchema).optional(),
     ignore: z.array(RuleIdSchema).max(128).optional(),
     criticalEntities: z.array(z.string().min(1).max(256)).max(128).optional(),
     criticalPaths: z.array(z.string().min(1).max(512)).max(128).optional(),
-    warningThresholds: z.record(RuleIdSchema, z.number().int().min(1).max(100_000)).optional(),
+    warningThresholds: z.partialRecord(RuleIdSchema, z.number().int().min(1).max(100_000)).optional(),
   })
   .strict()
 
 export const ReconciliationConfigSchema = z
   .object({
     /** Semantic comparison level. Raw discovery always keeps file-level relations. */
-    scope: z.enum(['file', 'module', 'package']).optional(),
+    scope: z.enum(['file', 'module', 'area', 'package']).optional(),
     /** Relation kinds that must have documentation declarations. Omit to require all observed kinds; [] disables this signal. */
     requiredRelationKinds: z.array(z.string().min(1).max(128)).max(128).optional(),
+    /** Limit missing-declaration findings to relations whose endpoints are internal project entities. */
+    requiredRelationTargets: z.enum(['all', 'internal']).optional(),
     includeOrphanedDocuments: z.boolean().optional(),
   })
   .strict()
 
+export const DocumentationAuditConfigSchema = z
+  .object({
+    /** Glob-like paths that should be compared for structure coverage. */
+    criticalPaths: z.array(z.string().min(1).max(512)).max(128).optional(),
+    /** Generated docs are checked for presence/freshness evidence only; content quality is skipped. */
+    generatedPaths: z.array(z.string().min(1).max(512)).max(128).optional(),
+    exclude: z.array(z.string().min(1).max(512)).max(128).optional(),
+    minWords: z.number().int().nonnegative().max(100_000).optional(),
+    requiredSections: z.array(z.string().min(1).max(128)).max(32).optional(),
+    requireExamples: z.boolean().optional(),
+    exactDuplicates: z.boolean().optional(),
+    defaultTier: z.enum(['tier-0', 'tier-1', 'tier-2']).optional(),
+    tierRules: z.array(z.object({
+      pattern: z.string().min(1).max(512),
+      tier: z.enum(['tier-0', 'tier-1', 'tier-2']),
+      critical: z.boolean().optional(),
+    }).strict()).max(128).optional(),
+    requiredCriticalMetadata: z.array(z.enum(['owner', 'lifecycle', 'sourceOfTruth', 'validationPath'])).max(4).optional(),
+  })
+  .strict()
+
 export const AnalysisConfigSchema = z
   .object({
     plugins: z
@@ -223,6 +246,18 @@ export const AnalysisConfigSchema = z
       })
       .strict()
       .optional(),
+    /**
+     * How code areas are derived — the unit of architecture between a package and a file.
+     * `roots` names directories that contain areas rather than being one (`src` holds
+     * `src/query`); `depth` is how many levels below such a root an area sits.
+     */
+    areas: z
+      .object({
+        depth: z.number().int().min(1).max(8).optional(),
+        roots: z.array(z.string().min(1).max(128)).max(32).optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict()
 
@@ -280,9 +315,11 @@ export const SurfacesConfigSchema = z
               'docbridge.relations',
               'docbridge.run',
               'docbridge.proposals',
+              'knowledge.search',
+              'knowledge.lookup',
             ]),
           )
-          .max(16)
+          .max(18)
           .optional(),
         transport: z.enum(['stdio', 'http']).optional(),
         http: z
@@ -298,6 +335,16 @@ export const SurfacesConfigSchema = z
   })
   .strict()
 
+/** One enrichment role: an installed Registry agent and the prompt version it is run with. */
+export const EnrichmentRoleSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    /** Defaults to `intelligence.registry.agentId`. */
+    agentId: z.string().min(1).max(256).optional(),
+    promptVersion: z.string().min(1).max(64).optional(),
+  })
+  .strict()
+
 export const IntelligenceConfigSchema = z
   .object({
     enabled: z.boolean().optional(),
@@ -357,11 +404,34 @@ export const IntelligenceConfigSchema = z
         agentId: z.string().min(1).max(256).optional(),
         agentRoot: z.string().min(1).max(512).optional(),
         runnerModule: z.string().min(1).max(512).optional(),
+        cli: z
+          .object({
+            /** Executable name or absolute path. Arguments are passed without a shell. */
+            command: z.string().min(1).max(512),
+            args: z.array(z.string().max(2_048)).max(64).optional(),
+          })
+          .strict()
+          .optional(),
         deterministic: z.boolean().optional(),
         timeoutMs: z.number().int().positive().max(600_000).optional(),
+        maxInputBytes: z.number().int().positive().max(50_000_000).optional(),
         maxTokens: z.number().int().positive().max(1_000_000).optional(),
         maxResponseBytes: z.number().int().positive().max(10_000_000).optional(),
         maxConcurrency: z.number().int().positive().max(64).optional(),
+        /** Byte budget of one enrichment context pack. Default 65536. */
+        maxPackBytes: z.number().int().min(4_096).max(4_000_000).optional(),
+        /**
+         * Which installed agent plays which enrichment role. The default is the configured agent
+         * as curator only. The adjudicator must be a different identity from both others.
+         */
+        roles: z
+          .object({
+            curator: EnrichmentRoleSchema.optional(),
+            reviewer: EnrichmentRoleSchema.optional(),
+            adjudicator: EnrichmentRoleSchema.optional(),
+          })
+          .strict()
+          .optional(),
       })
       .strict()
       .optional(),
@@ -468,12 +538,53 @@ export const DocumentationStandardV1ConfigSchema = z
     }
   })
 
+/**
+ * Retrieval tuning. Weights and parameters are configuration rather than code so a repository can
+ * change what its agents find first without a release, and so the change is recorded in the index.
+ */
+export const RetrievalConfigSchema = z
+  .object({
+    corpus: z
+      .object({
+        /** Project repository documents and modules into the index. On by default. */
+        enabled: z.boolean().optional(),
+      })
+      .strict()
+      .optional(),
+    weights: z.record(z.string().min(1).max(64), z.number().min(0).max(1_000)).optional(),
+    params: z
+      .object({ k1: z.number().min(0).max(100).optional(), b: z.number().min(0).max(1).optional() })
+      .strict()
+      .optional(),
+    benchmark: z
+      .object({
+        /** The golden retrieval suite the doctor measures hit@3 against. `docs/bench/retrieval-suite-v1.json` by default. */
+        suite: z.string().min(1).max(512).optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()
+
 export const ConformanceConfigSchema = z
   .object({
     documentationStandardV1: DocumentationStandardV1ConfigSchema.optional(),
   })
   .strict()
 
+export const RenderTemplateNameSchema = z.enum(['llms.txt', 'area', 'ownership', 'change-digest', 'overlay-review'])
+
+export const RenderConfigSchema = z
+  .object({
+    /**
+     * Project templates that replace the bundled ones, by template name, as paths relative to
+     * the project root. `ak-docs render <name> --print-template` prints the bundled template to
+     * start from.
+     */
+    templates: z.partialRecord(RenderTemplateNameSchema, z.string().min(1).max(512)).optional(),
+  })
+  .strict()
+
 export const DocBridgeConfigV1Schema = z
   .object({
     schemaVersion: z.literal(CONFIG_SCHEMA_VERSION),
@@ -494,6 +605,7 @@ export const DocBridgeConfigV1Schema = z
     routing: RoutingConfigSchema.optional(),
     gates: GatesConfigSchema.optional(),
     reconciliation: ReconciliationConfigSchema.optional(),
+    audit: z.object({ documentation: DocumentationAuditConfigSchema.optional() }).strict().optional(),
     analysis: AnalysisConfigSchema.optional(),
     rules: RulesConfigSchema.optional(),
     workflow: WorkflowConfigSchema.optional(),
@@ -503,15 +615,19 @@ export const DocBridgeConfigV1Schema = z
     intelligence: IntelligenceConfigSchema.optional(),
     federation: FederationConfigSchema.optional(),
     conformance: ConformanceConfigSchema.optional(),
+    retrieval: RetrievalConfigSchema.optional(),
+    render: RenderConfigSchema.optional(),
   })
   .strict()
 
 export type DocBridgeConfigV1 = z.infer<typeof DocBridgeConfigV1Schema>
+export type RenderConfig = z.infer<typeof RenderConfigSchema>
 export type AgentCorpusConfig = z.infer<typeof AgentCorpusConfigSchema>
 export type HumanCorpusConfig = z.infer<typeof HumanCorpusConfigSchema>
 export type DocumentationStandardV1Config = z.infer<typeof DocumentationStandardV1ConfigSchema>
 export type DocumentationStandardRuleId = z.infer<typeof DocumentationStandardRuleIdSchema>
 export type ReconciliationConfig = z.infer<typeof ReconciliationConfigSchema>
+export type DocumentationAuditConfig = z.infer<typeof DocumentationAuditConfigSchema>
 export type AnalysisConfig = z.infer<typeof AnalysisConfigSchema>
 export type RuleId = z.infer<typeof RuleIdSchema>
 export type RuleSeverity = z.infer<typeof RuleSeveritySchema>
@@ -519,3 +635,4 @@ export type RulesConfig = z.infer<typeof RulesConfigSchema>
 export type WorkflowConfig = z.infer<typeof WorkflowConfigSchema>
 export type RepositorySafetyConfig = z.infer<typeof RepositorySafetyConfigSchema>
 export type ReportConfig = z.infer<typeof ReportConfigSchema>
+export type RetrievalConfig = z.infer<typeof RetrievalConfigSchema>

package/src/conformance/documentation-standard-v1.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, realpathSync } from 'node:fs'
 import { isAbsolute, relative, resolve, sep } from 'node:path'
 
 import type {
@@ -11,6 +11,7 @@ import { buildDocBridgeIndex } from '../index-builder/build-index.js'
 import { scanHumanDocRecords } from '../index-builder/human-adapters/index.js'
 import { renderLlmsTxt } from '../index-builder/llms-txt.js'
 import { toPosix } from '../lib/paths.js'
+import type { DocBridgeIndexV1 } from '../schemas/doc-bridge-index.js'
 
 export const DOCUMENTATION_STANDARD_V1_ID = 'documentation-standard-v1' as const
 export const DOCUMENTATION_STANDARD_V1_STATUS = 'stable' as const
@@ -95,11 +96,10 @@ const fileEvidence = (
       evidence: { path, detail: 'Path escapes the project root.' },
     }
   }
-  if (!existsSync(abs)) {
-    return { exists: false, content: '', evidence: { path, detail: 'File does not exist.' } }
-  }
+  let fd: number | undefined
   try {
-    const stat = statSync(abs)
+    fd = openSync(abs, 'r')
+    const stat = fstatSync(fd)
     if (!stat.isFile()) {
       return { exists: false, content: '', evidence: { path, detail: 'Path is not a regular file.' } }
     }
@@ -120,7 +120,7 @@ const fileEvidence = (
         evidence: { path, detail: `Text evidence exceeds ${MAX_TEXT_EVIDENCE_BYTES} bytes.` },
       }
     }
-    const content = readFileSync(abs, 'utf8')
+    const content = readFileSync(fd, 'utf8')
     return {
       exists: content.trim().length > 0,
       content,
@@ -129,8 +129,15 @@ const fileEvidence = (
         detail: content.trim().length > 0 ? 'File exists and is non-empty.' : 'File is empty.',
       },
     }
-  } catch {
-    return { exists: false, content: '', evidence: { path, detail: 'File is not readable text.' } }
+  } catch (error) {
+    const code = error && typeof error === 'object' && 'code' in error ? error.code : undefined
+    return {
+      exists: false,
+      content: '',
+      evidence: { path, detail: code === 'ENOENT' ? 'File does not exist.' : 'File is not readable text.' },
+    }
+  } finally {
+    if (fd !== undefined) closeSync(fd)
   }
 }
 
@@ -180,6 +187,7 @@ const llmsRule = (
   root: string,
   config: DocBridgeConfigV1,
   options: DocumentationStandardV1Config,
+  generated: DocBridgeIndexV1,
 ): RuleDraft => {
   const llmsPath = config.index?.llmsTxt?.outFile ?? 'llms.txt'
   const llmsKey = safePath(root, llmsPath) ?? resolve(root, llmsPath)
@@ -190,8 +198,7 @@ const llmsRule = (
   }
   const paths = [llmsPath, ...rawSources.values()]
   const evidence = paths.map((path) => fileEvidence(root, path))
-  const generated = buildDocBridgeIndex({ root, config, write: false }).index
-  const expectedLlms = renderLlmsTxt(config, generated.knowledge, generated.project?.name ?? 'project')
+  const expectedLlms = renderLlmsTxt(config, generated.knowledge, generated.project?.name ?? 'project', { root })
   const llmsIsFresh = evidence[0]?.content === expectedLlms
   if (evidence[0]?.exists) {
     evidence[0] = {
@@ -278,8 +285,7 @@ const ecosystemContract = (
   }
 }
 
-const handoffsRule = (root: string, config: DocBridgeConfigV1): RuleDraft => {
-  const index = buildDocBridgeIndex({ root, config, write: false }).index
+const handoffsRule = (index: DocBridgeIndexV1): RuleDraft => {
   const handoffs = Object.values(index.handoffs ?? {})
   const ready = handoffs.filter(
     (handoff) =>
@@ -450,10 +456,12 @@ export const runDocumentationStandardV1 = (
   config: DocBridgeConfigV1,
 ): DocumentationConformanceReportV1 => {
   const options = config.conformance?.documentationStandardV1 ?? {}
+  // Two rules need the index. Building it projects and hashes the whole repository, so build once.
+  const index = buildDocBridgeIndex({ root, config, write: false }).index
   const drafts: RuleDraft[] = [
     humanDocsRule(root, config),
-    llmsRule(root, config, options),
-    handoffsRule(root, config),
+    llmsRule(root, config, options, index),
+    handoffsRule(index),
     contributionRule(root, options),
     markersRule(root, options, 'metadata', 'required'),
     linksRule(root, options),

package/src/discovery/areas.ts

@@ -0,0 +1,182 @@
+import { toPosix } from '../lib/paths.js'
+import { entityId } from './identity.js'
+
+/**
+ * Code areas: the unit of architecture between a package and a file.
+ *
+ * Reconciliation could only compare at file, module or package level, and most repositories are a
+ * single package — so every internal relation aggregated into one self-loop, which the comparison
+ * skips. The result was a repository with a thousand observed relations reporting zero
+ * diagnostics, and a health score of 100 out of 100 saying nothing at all.
+ *
+ * An area is a directory that groups modules. It is derived, not declared: the first directory
+ * level under a package's source roots, plus any path an ownership record already names — because
+ * a configuration saying `path: "src/mcp"` is a human telling us that directory is a unit, and the
+ * graph had no entity for it.
+ */
+
+export const AREA_ANALYZER_VERSION = '1.0.0'
+
+/**
+ * Directories that contain areas rather than being one.
+ *
+ * `src` is not an area in any useful sense; `src/query` is. When a package keeps its code under
+ * one of these, the area is the level below it.
+ */
+export const DEFAULT_AREA_ROOTS = ['src', 'lib', 'app', 'source', 'server', 'client', 'packages', 'apps'] as const
+
+export const DEFAULT_AREA_DEPTH = 1
+
+export type AreaModule = {
+  readonly moduleId: string
+  /** Repository-relative module path. */
+  readonly path: string
+  readonly packageId: string
+  /** Repository-relative package path; `.` for the root package. */
+  readonly packagePath: string
+}
+
+export type AreaOwnership = {
+  readonly id: string
+  readonly path: string
+}
+
+export type DerivedArea = {
+  readonly id: string
+  readonly path: string
+  readonly name: string
+  readonly packageId: string
+  /** The most specific area that encloses this one, when there is one. */
+  readonly parentId?: string
+  readonly moduleIds: readonly string[]
+  /** The ownership record that names exactly this path. */
+  readonly ownershipId?: string
+}
+
+export type DeriveAreasOptions = {
+  readonly modules: readonly AreaModule[]
+  readonly ownership?: readonly AreaOwnership[]
+  readonly depth?: number
+  readonly roots?: readonly string[]
+}
+
+/*
+ * Trailing separators are trimmed with a loop rather than /\/+$/: a quantified group anchored at
+ * the end backtracks quadratically on a path that is mostly separators, and a module path comes
+ * from the repository being scanned.
+ */
+const normalize = (path: string): string => {
+  const posix = toPosix(path).replace(/^\.\//, '')
+  let end = posix.length
+  while (end > 0 && posix[end - 1] === '/') end -= 1
+  return posix.slice(0, end)
+}
+
+const relativeToPackage = (modulePath: string, packagePath: string): string | undefined => {
+  if (packagePath === '.' || packagePath === '') return modulePath
+  const prefix = `${packagePath}/`
+  return modulePath.startsWith(prefix) ? modulePath.slice(prefix.length) : undefined
+}
+
+const join = (...parts: readonly string[]): string => parts.filter(Boolean).join('/')
+
+/**
+ * The area a module belongs to by convention: `depth` directory levels, counted below a source
+ * root when the module sits under one. A module directly in the package or in a bare source root
+ * has no conventional area — there is no directory grouping it with anything.
+ */
+export const conventionalAreaPath = (
+  module: AreaModule,
+  depth = DEFAULT_AREA_DEPTH,
+  roots: readonly string[] = DEFAULT_AREA_ROOTS,
+): string | undefined => {
+  const relative = relativeToPackage(normalize(module.path), normalize(module.packagePath))
+  if (relative === undefined) return undefined
+  const segments = relative.split('/')
+  segments.pop()
+  if (!segments.length) return undefined
+
+  const rootPrefix: string[] = []
+  let rest = segments
+  if (segments[0] && roots.includes(segments[0])) {
+    rootPrefix.push(segments[0])
+    rest = segments.slice(1)
+  }
+  const taken = rest.slice(0, Math.max(1, depth))
+  if (!taken.length) return undefined
+
+  const packagePath = normalize(module.packagePath)
+  return join(packagePath === '.' ? '' : packagePath, ...rootPrefix, ...taken)
+}
+
+const encloses = (candidate: string, path: string): boolean => path === candidate || path.startsWith(`${candidate}/`)
+
+/**
+ * Derive the areas of a repository.
+ *
+ * Every module is assigned to exactly one area — the most specific one containing it — so the
+ * containment graph stays a tree and an aggregation at area scope has one answer per module.
+ * Nested areas keep their shape: `src` names the area that holds what is directly in `src`, and
+ * `src/query` its own, with `src` recorded as the parent.
+ */
+export const deriveAreas = (options: DeriveAreasOptions): readonly DerivedArea[] => {
+  const depth = options.depth ?? DEFAULT_AREA_DEPTH
+  const roots = options.roots ?? [...DEFAULT_AREA_ROOTS]
+  const ownership = (options.ownership ?? []).map((record) => ({ ...record, path: normalize(record.path) }))
+
+  /** Candidate path to the package it belongs to. */
+  const candidates = new Map<string, string>()
+  for (const module of options.modules) {
+    const path = conventionalAreaPath(module, depth, roots)
+    if (path && !candidates.has(path)) candidates.set(path, module.packageId)
+  }
+  // An ownership record naming a directory that holds observed code is an area by declaration.
+  for (const record of ownership) {
+    if (!record.path || candidates.has(record.path)) continue
+    const owner = options.modules.find((module) => encloses(record.path, normalize(module.path)))
+    if (owner) candidates.set(record.path, owner.packageId)
+  }
+
+  const paths = [...candidates.keys()].sort()
+  const byLength = [...paths].sort((a, b) => b.length - a.length || a.localeCompare(b))
+  const moduleIds = new Map<string, string[]>(paths.map((path) => [path, []]))
+
+  for (const module of options.modules) {
+    const modulePath = normalize(module.path)
+    const area = byLength.find((candidate) => encloses(candidate, modulePath))
+    if (area) moduleIds.get(area)?.push(module.moduleId)
+  }
+
+  const ownershipByPath = new Map(ownership.map((record) => [record.path, record.id]))
+
+  return paths.map((path) => {
+    const parent = byLength.find((candidate) => candidate !== path && encloses(candidate, path))
+    const ownershipId = ownershipByPath.get(path)
+    return {
+      id: entityId('area', path),
+      path,
+      name: path.split('/').pop() ?? path,
+      packageId: candidates.get(path) as string,
+      ...(parent ? { parentId: entityId('area', parent) } : {}),
+      moduleIds: [...(moduleIds.get(path) ?? [])].sort(),
+      ...(ownershipId ? { ownershipId } : {}),
+    }
+  })
+}
+
+/**
+ * Ownership paths no observed entity lives under.
+ *
+ * A configured path that matches nothing is almost always a rename or a typo, and it is invisible
+ * until something looks: the handoff still resolves, it just points at a directory that no longer
+ * holds what it claims.
+ */
+export const unobservedOwnershipPaths = (
+  ownership: readonly AreaOwnership[],
+  observedPaths: readonly string[],
+): readonly AreaOwnership[] => {
+  const paths = observedPaths.map(normalize)
+  return ownership
+    .map((record) => ({ ...record, path: normalize(record.path) }))
+    .filter((record) => record.path && !paths.some((path) => encloses(record.path, path)))
+}