@latysh-development/monolith 0.0.0-stage → 0.1.0-alpha.1

package/dist/coordinatorium/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * COORDINATORIUM — deterministic project state management subsystem.
+ *
+ * This file defines the v0.1 state schema. Tactical Coordinatorium
+ * (mission lifecycle) is implemented. Strategic Coordinatorium (product /
+ * subsystem state) is reserved — `strategic.systems` exists in the schema
+ * but nothing in this package writes to it yet.
+ */
+export declare const STATE_SCHEMA_VERSION = 2;
+/**
+ * The only prior schema version `state-keeper.ts` knows how to migrate
+ * from. A v1 file has `tactical.missions` but no reliable
+ * `tactical.checkpoints` (COORDINATORIUM-002 bumped the version precisely
+ * so that a pre-002 binary — hardcoded to `STATE_SCHEMA_VERSION === 1` —
+ * refuses to touch a v2 file instead of silently dropping its checkpoints
+ * on its next read-modify-write cycle; see ADR-008's 2026-10-21
+ * COORDINATORIUM-002 compatibility-fix addendum).
+ */
+export declare const LEGACY_SCHEMA_VERSION_V1 = 1;
+export type MissionStatus = 'in_progress' | 'completed' | 'failed' | 'cancelled';
+export type MissionResult = Exclude<MissionStatus, 'in_progress'>;
+export interface Mission {
+    id: string;
+    title: string;
+    system: string;
+    status: MissionStatus;
+    startedAt: string;
+    updatedAt: string;
+    summary: string | null;
+}
+/** Reserved for the Strategic Coordinatorium. No mutations in v0.1. */
+export interface StrategicState {
+    systems: Record<string, unknown>;
+}
+/**
+ * A durable, append-only progress note attached to exactly one Mission
+ * (COORDINATORIUM-002). Checkpoints are never updated or deleted once
+ * created — `id` and `createdAt` are stamped by the keeper, never
+ * caller-supplied, exactly like `Mission.id`/`startedAt`.
+ */
+export interface Checkpoint {
+    id: string;
+    missionId: string;
+    createdAt: string;
+    summary: string;
+    remainingSteps: string[];
+    context: string | null;
+}
+export interface TacticalState {
+    missions: Record<string, Mission>;
+    /**
+     * Sibling top-level map to `missions`, not nested inside `Mission` — see
+     * ADR-008's 2026-10-21 Mission Checkpoints addendum. Required for
+     * `schemaVersion: 2` (the current, in-memory shape returned by
+     * `validateState`/`readState` — every v2 writer always includes it).
+     * A `schemaVersion: 1` file on disk may be missing this key entirely;
+     * `state-keeper.ts`'s v1→v2 migration defaults it to `{}` on read. See
+     * `LEGACY_SCHEMA_VERSION_V1`.
+     */
+    checkpoints: Record<string, Checkpoint>;
+}
+export interface CoordinatoriumState {
+    schemaVersion: typeof STATE_SCHEMA_VERSION;
+    revision: number;
+    strategic: StrategicState;
+    tactical: TacticalState;
+}
+export declare function createInitialState(): CoordinatoriumState;
+//# sourceMappingURL=types.d.ts.map

package/dist/coordinatorium/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/coordinatorium/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEjF,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;AAElE,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,OAAO,oBAAoB,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,cAAc,CAAC;IAC1B,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED,wBAAgB,kBAAkB,IAAI,mBAAmB,CAOxD"}

package/dist/coordinatorium/types.js

@@ -0,0 +1,27 @@
+/**
+ * COORDINATORIUM — deterministic project state management subsystem.
+ *
+ * This file defines the v0.1 state schema. Tactical Coordinatorium
+ * (mission lifecycle) is implemented. Strategic Coordinatorium (product /
+ * subsystem state) is reserved — `strategic.systems` exists in the schema
+ * but nothing in this package writes to it yet.
+ */
+export const STATE_SCHEMA_VERSION = 2;
+/**
+ * The only prior schema version `state-keeper.ts` knows how to migrate
+ * from. A v1 file has `tactical.missions` but no reliable
+ * `tactical.checkpoints` (COORDINATORIUM-002 bumped the version precisely
+ * so that a pre-002 binary — hardcoded to `STATE_SCHEMA_VERSION === 1` —
+ * refuses to touch a v2 file instead of silently dropping its checkpoints
+ * on its next read-modify-write cycle; see ADR-008's 2026-10-21
+ * COORDINATORIUM-002 compatibility-fix addendum).
+ */
+export const LEGACY_SCHEMA_VERSION_V1 = 1;
+export function createInitialState() {
+    return {
+        schemaVersion: STATE_SCHEMA_VERSION,
+        revision: 0,
+        strategic: { systems: {} },
+        tactical: { missions: {}, checkpoints: {} },
+    };
+}

package/dist/discovery/compose.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DISCOVERY-001C — unified Project Map composer (ADR-021). Internal.
+ *
+ * A pure transformation of TWO finished results into one Markdown text: a `DiscoveryResult`
+ * (structural facts, evidence OBSERVED_FILE-class) and a `DocumentationResult` (what documents
+ * claim, evidence DOCUMENT_TEXT). It reads no file, starts no analyzer, calls no model, opens no
+ * connection, keeps no clock and modifies neither input.
+ *
+ * Identity. Neither contract carries a project identity (no id, no root, no digest); both only say
+ * that they were derived from "a traversal". So the composer cannot confirm that the two results
+ * describe the same project and says so in the output. It does not guess from paths or names.
+ *
+ * Trust. The two sources are never merged: structure comes from the existing renderer, unchanged;
+ * documentation gets its own section, and every statement made by a document is shown as an
+ * unverified claim. The statuses of the two analyzers are shown side by side, never combined.
+ *
+ * Markdown safety. Every untrusted string goes through the renderer's `markdownCodeSpan` (control and
+ * bidi characters are shown as [U+XXXX], an inline code span cannot be closed by its content) and sits
+ * in a list item; headings and structure are fixed text. Document text is never interpreted.
+ */
+import { type DiscoveryResult } from './contracts.js';
+import { type DocumentationResult } from './docs.js';
+/**
+ * Composes the unified Project Map. Throws `DiscoveryError('RESULT_INVALID')` if either input fails
+ * its own validator (the message names which input and the first violations, never a value).
+ */
+export declare function composeProjectMap(discovery: DiscoveryResult, documentation: DocumentationResult): string;
+//# sourceMappingURL=compose.d.ts.map

package/dist/discovery/compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/discovery/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAqD,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACzG,OAAO,EAKL,KAAK,mBAAmB,EAEzB,MAAM,WAAW,CAAC;AAgCnB;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,eAAe,EAAE,aAAa,EAAE,mBAAmB,GAAG,MAAM,CAoGxG"}

package/dist/discovery/compose.js

@@ -0,0 +1,159 @@
+/**
+ * DISCOVERY-001C — unified Project Map composer (ADR-021). Internal.
+ *
+ * A pure transformation of TWO finished results into one Markdown text: a `DiscoveryResult`
+ * (structural facts, evidence OBSERVED_FILE-class) and a `DocumentationResult` (what documents
+ * claim, evidence DOCUMENT_TEXT). It reads no file, starts no analyzer, calls no model, opens no
+ * connection, keeps no clock and modifies neither input.
+ *
+ * Identity. Neither contract carries a project identity (no id, no root, no digest); both only say
+ * that they were derived from "a traversal". So the composer cannot confirm that the two results
+ * describe the same project and says so in the output. It does not guess from paths or names.
+ *
+ * Trust. The two sources are never merged: structure comes from the existing renderer, unchanged;
+ * documentation gets its own section, and every statement made by a document is shown as an
+ * unverified claim. The statuses of the two analyzers are shown side by side, never combined.
+ *
+ * Markdown safety. Every untrusted string goes through the renderer's `markdownCodeSpan` (control and
+ * bidi characters are shown as [U+XXXX], an inline code span cannot be closed by its content) and sits
+ * in a list item; headings and structure are fixed text. Document text is never interpreted.
+ */
+import { DiscoveryError } from './contracts.js';
+import { validateDiscoveryResult } from './contracts.js';
+import { DOCUMENTATION_DIAGNOSTIC_AFFECTS_COMPLETENESS, validateDocumentationResult, } from './docs.js';
+import { markdownCodeSpan as code, renderProjectMapProposal } from './render.js';
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+function textShown(text, status) {
+    if (status === 'WITHHELD')
+        return '(withheld: contains unsafe characters)';
+    return status === 'TRUNCATED' ? `${code(text)} (truncated)` : code(text);
+}
+function lines(o) {
+    const { startLine, endLine } = o.source;
+    if (startLine === undefined)
+        return 'whole file';
+    return endLine === undefined || endLine === startLine ? `line ${startLine}` : `lines ${startLine}-${endLine}`;
+}
+function docDiagnosticLine(d) {
+    const known = Object.prototype.hasOwnProperty.call(DOCUMENTATION_DIAGNOSTIC_AFFECTS_COMPLETENESS, d.code);
+    const origin = d.code.startsWith('TRAVERSAL_')
+        ? 'reported by the traversal'
+        : known && DOCUMENTATION_DIAGNOSTIC_AFFECTS_COMPLETENESS[d.code]
+            ? 'documentation analysis; makes the result PARTIAL'
+            : 'documentation analysis; does not by itself make the result PARTIAL';
+    const parts = [`${code(d.code)} (${origin})`];
+    if (d.path !== undefined)
+        parts.push(`path ${code(d.path)}`);
+    if (d.count !== undefined)
+        parts.push(`count ${d.count}`);
+    return `- ${parts.join(', ')}: ${code(d.message)}`;
+}
+/** Lowers every heading of the (trusted, fixed-text) renderer output by two levels. Project data cannot start a line with `#`: it only appears inside code spans, and line breaks inside it are escaped. */
+const demote = (markdown) => markdown.replace(/^(#+) /gm, '##$1 ');
+/**
+ * Composes the unified Project Map. Throws `DiscoveryError('RESULT_INVALID')` if either input fails
+ * its own validator (the message names which input and the first violations, never a value).
+ */
+export function composeProjectMap(discovery, documentation) {
+    const dv = validateDiscoveryResult(discovery);
+    if (dv.length > 0)
+        throw new DiscoveryError('RESULT_INVALID', `cannot compose: the DiscoveryResult failed validation (${dv.length} violation(s)): ${dv.slice(0, 3).join('; ')}`);
+    const cv = validateDocumentationResult(documentation);
+    if (cv.length > 0)
+        throw new DiscoveryError('RESULT_INVALID', `cannot compose: the DocumentationResult failed validation (${cv.length} violation(s)): ${cv.slice(0, 3).join('; ')}`);
+    const out = [];
+    const line = (s = '') => void out.push(s);
+    line('# PROJECT MAP');
+    line();
+    line('This document puts two separate results side by side: structure observed in the project tree, and what the project’s Markdown documents say. They are not merged and not compared with each other. It is a proposal for a reader to review.');
+    // ------------------------------------------------------------ structure
+    line();
+    line('## Observed Project Structure');
+    line();
+    line('- Source: a Discovery result (evidence from the traversal: directory entries, file names, package.json fields).');
+    line('- Where the text below says documentation was not analysed, it refers to this Discovery result only; see Documentation Overview for the separate documentation result.');
+    line();
+    out.push(demote(renderProjectMapProposal(discovery)).replace(/\n+$/, ''));
+    // ---------------------------------------------------------------- docs
+    const { stats, observations } = documentation;
+    line();
+    line('## Documentation Overview');
+    line();
+    line('- Source: a Documentation result. Everything below is the content of documents as written by their authors. It is UNVERIFIED: it has not been compared with the code and may be wrong or out of date.');
+    line(`- Analysis completeness: ${documentation.completeness}`);
+    line(documentation.completeness === 'PARTIAL'
+        ? '  - Some documentation information was not extracted; see Diagnostics below. Counts are lower bounds.'
+        : '  - Everything inside the declared scope was handled. COMPLETE does not mean that every Markdown construct was recognised; see the supported subset in Trust & Coverage Notes.');
+    line(`- Reproducible: ${documentation.reproducible ? 'Yes' : 'No'}`);
+    line(`- Traversal behind it: completeness ${documentation.traversal.completeness}, reproducible ${documentation.traversal.reproducible ? 'Yes' : 'No'}`);
+    line(`- Schema version: ${documentation.schemaVersion}`);
+    line(`- Documents listed as present: ${stats.candidateDocuments}; analysed: ${stats.documentsAnalyzed}; present but not analysed: ${stats.documentsNotAnalyzed}`);
+    line(`- Bytes read: ${stats.bytesRead}; observations recorded: ${stats.observations}`);
+    const byPath = new Map();
+    for (const o of observations) {
+        const g = byPath.get(o.source.path);
+        if (g)
+            g.push(o);
+        else
+            byPath.set(o.source.path, [o]);
+    }
+    line();
+    line('### Documents');
+    line();
+    if (byPath.size === 0)
+        line('- No documents were recorded.');
+    for (const [path, group] of byPath) {
+        line(`- ${code(path)}`);
+        for (const o of group) {
+            if (o.kind === 'DOCUMENT_PRESENT') {
+                const size = [o.bytes === undefined ? '' : plural(o.bytes, 'byte', 'bytes'), o.lines === undefined ? '' : plural(o.lines, 'line', 'lines')].filter(Boolean).join(', ');
+                line(`  - File observed (evidence ${o.evidence}); ${o.analysis === 'ANALYZED' ? 'content analysed' : 'content NOT analysed'}${size ? `; ${size}` : ''}`);
+            }
+        }
+        const headings = group.filter((o) => o.kind === 'HEADING');
+        const sections = group.filter((o) => o.kind === 'SECTION');
+        const links = group.filter((o) => o.kind === 'LINK');
+        if (headings.length > 0) {
+            line(`  - Headings written in the document (${headings.length} recorded; evidence ${headings[0].evidence}):`);
+            for (const o of headings)
+                if (o.kind === 'HEADING')
+                    line(`    - ${lines(o)}, level ${o.level}: ${textShown(o.text, o.textStatus)}`);
+        }
+        if (sections.length > 0) {
+            line(`  - Text ranges between headings (${sections.length} recorded; evidence ${sections[0].evidence}):`);
+            for (const o of sections)
+                if (o.kind === 'SECTION')
+                    line(`    - ${lines(o)}, opened by heading ${o.headingOrdinal}${o.parentHeadingOrdinal === undefined ? '' : ` under heading ${o.parentHeadingOrdinal}`}: ${plural(o.ownTextLineGroups, 'text line group', 'text line groups')} of its own`);
+        }
+        if (links.length > 0) {
+            line(`  - Inline links written in the document (${links.length} recorded, not necessarily all; evidence ${links[0].evidence}; targets are not resolved or checked):`);
+            for (const o of links)
+                if (o.kind === 'LINK')
+                    line(`    - ${lines(o)}, ${o.linkType}: target ${code(o.target)}, text ${textShown(o.text, o.textStatus)}`);
+        }
+    }
+    line();
+    line('### Documentation Diagnostics');
+    line();
+    if (documentation.diagnostics.length === 0)
+        line('- No diagnostics were reported.');
+    for (const d of documentation.diagnostics)
+        line(docDiagnosticLine(d));
+    // --------------------------------------------------------------- trust
+    const limits = documentation.limits;
+    line();
+    line('## Trust & Coverage Notes');
+    line();
+    line('- Structural facts in Observed Project Structure were obtained by observing the file tree and, for package.json, declared fields. They are observations, not verified descriptions of how the project works.');
+    line('- Everything in Documentation Overview is unverified document content (evidence DOCUMENT_TEXT). The only observed item there is that a document file exists (evidence OBSERVED_FILE). No documentary statement has been confirmed by the code.');
+    line('- Common origin of the two results is NOT confirmed: neither result carries a project identity, so this document cannot tell whether they describe the same project or the same moment. No such link is asserted.');
+    line('- The two analyzers keep separate statuses and they are not combined:');
+    line(`  - Structural Discovery: completeness ${discovery.completeness}, reproducible ${discovery.reproducible ? 'Yes' : 'No'}`);
+    line(`  - Documentation Analysis: completeness ${documentation.completeness}, reproducible ${documentation.reproducible ? 'Yes' : 'No'}`);
+    line('- COMPLETE refers only to the scope each analyzer declares. It is not a statement that the project or its documents were fully understood.');
+    line('- Documentation scope: README.md at the project root and *.md files under docs/ that the traversal listed. Supported Markdown subset: ATX headings; one-line inline links; fenced code blocks, front matter, HTML comment lines and indented lines are skipped. Not recognised: setext headings, reference-style links, autolinks, images, raw HTML, constructs split over lines, headings or links inside quotes or lists.');
+    line('- Link and heading counts are counts of recognised constructs, not the number of links or headings in a document.');
+    line(`- Documentation limits: documents ${limits.maxDocuments}; bytes per document ${limits.maxDocumentBytes}; total bytes ${limits.maxTotalBytes}; headings per document ${limits.maxHeadingsPerDocument}; links per document ${limits.maxLinksPerDocument}; text length ${limits.maxTextLength}; link target length ${limits.maxTargetLength}; line length ${limits.maxLineLength}; observations ${limits.maxObservations}; diagnostics ${limits.maxDiagnostics}.`);
+    line('- Not observing something is not evidence that it does not exist.');
+    return `${out.join('\n')}\n`;
+}

package/dist/discovery/contracts.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Discovery contract, schema version 1 (ADR-021 §2-§4). Internal: not exported from `src/index.ts`.
+ *
+ * A fact says what the project's bytes show (`DETECTED`) or what a named rule derived from
+ * DETECTED facts (`INTERPRETED`). Three properties are kept apart on purpose and never
+ * folded into one another:
+ *  - `completeness`: did the scan cover what it declared (`COMPLETE` | `PARTIAL`);
+ *  - `reproducible`: would a second scan of the same unchanged tree return this result;
+ *  - `level` of a fact: how it was obtained. There is no numeric confidence.
+ */
+export declare const DISCOVERY_SCHEMA_VERSION = 1;
+export type DiscoveryLevel = 'DETECTED' | 'INTERPRETED';
+/** The level is a function of the kind (ADR-021 §2): never chosen per fact, checked by the validator. */
+export declare const FACT_LEVEL_BY_KIND: {
+    /** A directory exists in the inventory. */
+    readonly DIRECTORY: "DETECTED";
+    /** A file with a conventional name exists (the basis of an entrypoint candidate). */
+    readonly FILE_PRESENT: "DETECTED";
+    /**
+     * `value` files with extension `object` exist; `subject` is the language that extension maps to.
+     * An aggregate: `value` counts every file the traversal listed, `sources` is only a sample of them
+     * (see `sourceCoverage`).
+     */
+    readonly LANGUAGE_BY_EXTENSION: "DETECTED";
+    /** A file with the name of a known manifest exists. Says nothing about its content or about runtime use. */
+    readonly MANIFEST_PRESENT: "DETECTED";
+    /** A manifest declares dependency `object` in section `value`. Not resolved, not installed, not verified. */
+    readonly DEPENDENCY_DECLARED: "DETECTED";
+    /** A manifest declares a script named `object`. The command is never stored and never run. */
+    readonly SCRIPT_DECLARED: "DETECTED";
+    /** A file name convention suggests `subject` may start the program. A candidate, never a verified entrypoint. */
+    readonly ENTRYPOINT_CANDIDATE: "INTERPRETED";
+};
+export type DiscoveryFactKind = keyof typeof FACT_LEVEL_BY_KIND;
+export type DiscoveryObservation = 'directory-entry' | 'file-entry' | 'extension' | 'file-name' | 'manifest-field';
+export interface DiscoverySource {
+    /** Project-relative, `/`-separated; never absolute, never contains `..`. */
+    path: string;
+    /** What kind of observation backs the fact. */
+    observation: DiscoveryObservation;
+    /** For `manifest-field`: an RFC 6901 JSON Pointer into the manifest (e.g. `/dependencies/@scope~1pkg`). */
+    field?: string;
+}
+export interface DiscoveryFact {
+    /** 16 hex of sha256 over (schemaVersion, kind, subject, object, value); see `computeFactId`. */
+    id: string;
+    kind: DiscoveryFactKind;
+    level: DiscoveryLevel;
+    subject: string;
+    object?: string;
+    value?: string;
+    /** Name of the detection (DETECTED) or derivation (INTERPRETED) rule. */
+    rule: string;
+    /** INTERPRETED only: ids of the DETECTED facts the interpretation rests on. */
+    basis?: string[];
+    /**
+     * At least one; sorted. For a `LANGUAGE_BY_EXTENSION` aggregate these are a deterministic SAMPLE
+     * (the first `min(value, limits.maxSourcesPerFact)` paths in UTF-16 order), not the whole evidence:
+     * `value` is computed over all files and is checked against the sample size by the validator.
+     * Every other kind rests on exactly the sources it lists. See `sourceCoverage`.
+     */
+    sources: DiscoverySource[];
+}
+/**
+ * Whether a fact's `sources` are all of its evidence (`FULL`) or a sample of it (`SAMPLE`).
+ * Derived, not stored: only a `LANGUAGE_BY_EXTENSION` aggregate with more files than listed sources
+ * is a `SAMPLE`. Coverage says nothing about the scan: a count over a `PARTIAL` traversal is a lower
+ * bound, and that is stated by `DiscoveryResult.completeness` and `traversal.completeness`.
+ */
+export type SourceCoverage = 'FULL' | 'SAMPLE';
+export declare function sourceCoverage(fact: Pick<DiscoveryFact, 'kind' | 'value' | 'sources'>): SourceCoverage;
+/**
+ * Closed list. The value says whether the code makes the result `PARTIAL` (something inside the
+ * declared scope was not extracted) or only reports a scope policy or an unanalysed area.
+ */
+export declare const EXTRACTION_DIAGNOSTIC_AFFECTS_COMPLETENESS: {
+    readonly INPUT_PATH_REJECTED: true;
+    readonly LIMIT_DIRECTORY_FACTS: true;
+    readonly LIMIT_LANGUAGE_FACTS: true;
+    readonly LIMIT_MANIFEST_FACTS: true;
+    readonly LIMIT_MANIFEST_READS: true;
+    readonly LIMIT_DEPENDENCIES: true;
+    readonly LIMIT_SCRIPTS: true;
+    readonly LIMIT_ENTRYPOINT_FACTS: true;
+    readonly LIMIT_FACTS: true;
+    readonly LIMIT_DIAGNOSTICS: true;
+    readonly MANIFEST_READ_FAILED: true;
+    readonly MANIFEST_TOO_LARGE: true;
+    readonly MANIFEST_PARSE_ERROR: true;
+    readonly MANIFEST_FIELD_INVALID: true;
+    readonly MANIFEST_VALUE_REJECTED: true;
+    readonly MANIFEST_EMPTY: false;
+    readonly MANIFEST_NOT_REGULAR_FILE: false;
+    readonly MANIFEST_CONTENT_NOT_ANALYZED: false;
+    readonly NESTED_MONOLITH_STATE_EXCLUDED: false;
+    readonly NESTED_MONOLITH_UNCONFIRMED: false;
+};
+export type ExtractionDiagnosticCode = keyof typeof EXTRACTION_DIAGNOSTIC_AFFECTS_COMPLETENESS;
+/** Whether a second scan of the same unchanged tree must return the same diagnostic. */
+export declare const EXTRACTION_DIAGNOSTIC_IS_STABLE: Record<ExtractionDiagnosticCode, boolean>;
+export interface DiscoveryDiagnostic {
+    /** An extraction code, or `TRAVERSAL_<code>` for a diagnostic carried over from the traversal. */
+    code: string;
+    /** Project-relative path, when the diagnostic concerns one. */
+    path?: string;
+    /** Total occurrences, present on a summary line. */
+    count?: number;
+    /** Fixed text; never a raw error message, a file content excerpt or an absolute path. */
+    message: string;
+}
+export interface DiscoveryLimits {
+    /** Directory facts (paths of at most `maxDirectoryDepth` segments), shallowest first. */
+    maxDirectoryFacts: number;
+    maxDirectoryDepth: number;
+    /** Distinct (language, extension) facts. */
+    maxLanguageFacts: number;
+    /** Manifest presence facts, shallowest first. */
+    maxManifestFacts: number;
+    /** Manifests whose content is read (only `package.json` is parsed in this version). */
+    maxManifestReads: number;
+    /** Size cap of one manifest, bytes. */
+    maxManifestBytes: number;
+    /** Dependency facts per manifest. */
+    maxDependenciesPerManifest: number;
+    /** Script facts per manifest. */
+    maxScriptsPerManifest: number;
+    maxEntrypointFacts: number;
+    /** Cap on the whole `facts` array; a final guard, normally never reached. */
+    maxFacts: number;
+    maxDiagnostics: number;
+    /** Longest dependency or script name that is kept. */
+    maxNameLength: number;
+    /** Sources listed for a language aggregate: a sample of at most this many files. */
+    maxSourcesPerFact: number;
+}
+export interface DiscoveryStats {
+    /** Traversal entries received. */
+    inputEntries: number;
+    /**
+     * Entries that did not reach extraction: a rejected path or kind, a path repeated in the input
+     * (collapsed to one entry) or an entry inside confirmed nested MONOLITH state.
+     */
+    excludedEntries: number;
+    /** Files whose extension maps to no known language. Reported, not guessed. */
+    filesWithoutKnownLanguage: number;
+    manifestsFound: number;
+    /** `package.json` files a read was attempted on (a failed read counts; see the diagnostics). */
+    manifestsRead: number;
+    facts: number;
+}
+export interface DiscoveryResult {
+    schemaVersion: typeof DISCOVERY_SCHEMA_VERSION;
+    limits: DiscoveryLimits;
+    /** `PARTIAL` when the traversal was `PARTIAL` or any completeness-affecting diagnostic exists. */
+    completeness: 'COMPLETE' | 'PARTIAL';
+    /** A second scan of the unchanged tree would return this result (traversal and extraction). */
+    reproducible: boolean;
+    /** What the traversal reported, kept visible next to the combined verdict. */
+    traversal: {
+        completeness: 'COMPLETE' | 'PARTIAL';
+        reproducible: boolean;
+    };
+    stats: DiscoveryStats;
+    /** Sorted by (kind, subject, object, value) in UTF-16 code-unit order. */
+    facts: DiscoveryFact[];
+    /**
+     * Sorted by `compareDiagnostics`: completeness-affecting extraction codes, then traversal codes,
+     * then the other extraction codes; each by code, path, message, count. The one exception is a
+     * `LIMIT_DIAGNOSTICS` summary, which is always first when the list was cut.
+     */
+    diagnostics: DiscoveryDiagnostic[];
+}
+export type DiscoveryErrorCode = 'INVALID_LIMITS' | 'INVALID_INPUT' | 'ID_COLLISION' | 'RESULT_INVALID';
+/** Extraction cannot proceed safely or produced a result the validator rejects: no result exists (FAILED). */
+export declare class DiscoveryError extends Error {
+    readonly code: DiscoveryErrorCode;
+    constructor(code: DiscoveryErrorCode, message: string);
+}
+/** UTF-16 code-unit order; never `localeCompare` (ADR-021 §4). */
+export declare function compareUtf16(a: string, b: string): number;
+/** 16 hex of sha256 over the canonical tuple. Provenance, level, rule and positions are excluded. */
+export declare function computeFactId(kind: string, subject: string, object?: string, value?: string): string;
+/** A project-relative POSIX path with no empty, `.` or `..` segment, no NUL/control/backslash and no drive prefix. */
+export declare function isSafeRelativePath(p: unknown): p is string;
+export declare const DEPENDENCY_SECTIONS: readonly ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+/** RFC 6901 token escaping. */
+export declare const pointerToken: (s: string) => string;
+export declare function isKeepableName(name: string, max: number): boolean;
+/**
+ * Diagnostic order: completeness-affecting extraction codes (0), traversal codes (1), the other
+ * extraction codes (2); then code, path, message, count. `count` closes the tie so that no two
+ * different diagnostics compare equal.
+ */
+export declare function compareDiagnostics(a: DiscoveryDiagnostic, b: DiscoveryDiagnostic): number;
+export declare function compareFacts(a: DiscoveryFact, b: DiscoveryFact): number;
+export declare function compareSources(a: DiscoverySource, b: DiscoverySource): number;
+/**
+ * Check of a `DiscoveryResult` against the schema-1 contract. Returns the violations (empty = valid);
+ * `extractProjectFacts` throws `DiscoveryError('RESULT_INVALID')` rather than return a result that
+ * fails it (FAILED, ADR-021 §5).
+ *
+ * Input is `unknown` on purpose: a malformed value yields violations, never a `TypeError`. A violation
+ * names a location (`facts[3]`) and a rule, and never repeats a value from the input, so an untrusted
+ * result cannot reach a log through it. At most 100 violations are returned.
+ *
+ * Scope: plain JSON-like data (a producer's output or `JSON.parse` output). An object with accessors
+ * that throw, or a `Proxy`, is not defended against (ADR-021 does not require it). The validator is
+ * not a general schema library: it checks this contract and nothing else.
+ */
+export declare function validateDiscoveryResult(result: unknown): string[];
+//# sourceMappingURL=contracts.d.ts.map

package/dist/discovery/contracts.d.ts.map

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