@ttsc/evidence 0.30.3 → 0.31.0

package/lib/internal/normalizeSwaggerDocument.js

@@ -2,6 +2,324 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeSwaggerDocument = void 0;
 const utils_1 = require("@typia/utils");
-/** @internal */
-const normalizeSwaggerDocument = (input) => utils_1.OpenApiConverter.upgradeDocument(input);
+/**
+ * Normalizes schema targets without letting a version converter rebase their
+ * references to an unrelated component with the same final token.
+ *
+ * Raw 3.1 and 3.2 schema references are lowered to private component names
+ * before conversion. Each selected raw target is converted as a schema in its
+ * own right, so a pointer into a tuple still selects that schema when the
+ * converter changes `items` to `prefixItems`. The names stay inside this call;
+ * the digest reader receives the original reference and pointer identity.
+ * Missing and foreign references have no private target and cannot accidentally
+ * bind to a local component. This does not fetch referenced documents.
+ *
+ * Only schema positions are rewritten. Example, default, const, enum and
+ * extension payloads are copied without interpreting their data as schemas.
+ * Existing emended documents and other versions keep the ordinary conversion
+ * path. The supplied reader is the bridge's own strict component URI reader,
+ * shared with its post-conversion digest resolution.
+ *
+ * Copies, alias targets and provenance are retained for one source conversion
+ * and its operation digests, not in a process-wide cache. Reference proxies
+ * share targets by decoded pointer. Nested targets are copied and converted
+ * separately from the containing schema because their normalized locations can
+ * differ; literal copies preserve each data occurrence. These costs, and
+ * recursion depth, are not bounded by the reader's raw-byte limit. Weak
+ * identity maps terminate copy/visitor cycles; they do not impose a total
+ * memory quota or change the converter's own treatment of cyclic schemas.
+ *
+ * @internal
+ */
+const normalizeSwaggerDocument = (input, componentAt) => {
+    const references = new Map();
+    let prepared = input;
+    if (input !== null &&
+        typeof input === "object" &&
+        typeof input.openapi === "string" &&
+        (input.openapi.startsWith("3.1") || input.openapi.startsWith("3.2")) &&
+        !(input.openapi.startsWith("3.2") && input["x-typia-emended-v12"] === true)) {
+        const writtenPointers = new Set();
+        const copy = (value, copies = new WeakMap()) => {
+            if (value === null || typeof value !== "object") {
+                if (typeof value === "string" && value.startsWith("#"))
+                    try {
+                        writtenPointers.add(decodeURIComponent(value.slice(1)));
+                    }
+                    catch {
+                        // A malformed spelling cannot name a generated alias.
+                    }
+                return value;
+            }
+            const previous = copies.get(value);
+            if (previous !== undefined)
+                return previous;
+            const result = Array.isArray(value) ? [] : {};
+            copies.set(value, result);
+            for (const [key, child] of Object.entries(value))
+                Object.defineProperty(result, key, {
+                    value: copy(child, copies),
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+            return result;
+        };
+        prepared = copy(input);
+        // YAML anchors can share one object between a schema and literal data.
+        // Detach every data holder before any reference is rewritten.
+        const detachLiterals = swaggerSchemaVisitor(() => { }, (value, holder, key) => {
+            if (Object.hasOwn(holder, key))
+                holder[key] = copy(value);
+        });
+        detachLiterals.document(prepared);
+        const components = (prepared.components ??= {});
+        const schemas = (components.schemas ??= {});
+        const targets = new Map();
+        const convertedTargets = new Map();
+        let sequence = 0;
+        const reference = (spelling) => {
+            // Keep each spelling for the literal left at a recursive boundary. Its
+            // decoded pointer, rather than this private name, identifies the guard.
+            const known = targets.get(spelling);
+            if (known !== undefined)
+                return known;
+            const target = componentAt(input.components ?? {}, spelling);
+            let key;
+            do
+                key = `_ttsc_schema_reference_${sequence++}`;
+            while (Object.hasOwn(schemas, key) ||
+                writtenPointers.has(`/components/schemas/${key}`));
+            const alias = `#/components/schemas/${key}`;
+            targets.set(spelling, alias);
+            const preserved = { reference: spelling, pointer: target?.pointer, key };
+            references.set(alias, preserved);
+            // Reserve the alias before walking its target: mutual and self references
+            // become finite edges, rather than recursively expanded object copies.
+            if (target !== undefined) {
+                let targetKey = convertedTargets.get(target.pointer);
+                if (targetKey === undefined) {
+                    const prefix = "/components/schemas/";
+                    const token = target.pointer.startsWith(prefix)
+                        ? target.pointer.slice(prefix.length)
+                        : undefined;
+                    const originalKey = token !== undefined && !token.includes("/")
+                        ? token.replaceAll("~1", "/").replaceAll("~0", "~")
+                        : undefined;
+                    targetKey =
+                        originalKey !== undefined && Object.hasOwn(schemas, originalKey)
+                            ? originalKey
+                            : key;
+                    convertedTargets.set(target.pointer, targetKey);
+                    if (targetKey === key) {
+                        Object.defineProperty(schemas, key, {
+                            value: copy(target.value),
+                            writable: true,
+                            enumerable: true,
+                            configurable: true,
+                        });
+                        detachLiterals.schema(schemas[key]);
+                    }
+                }
+                preserved.key = targetKey;
+                if (targetKey !== key)
+                    Object.defineProperty(schemas, key, {
+                        value: {
+                            $ref: `#/components/schemas/${encodeURIComponent(targetKey.replaceAll("~", "~0").replaceAll("/", "~1"))}`,
+                        },
+                        writable: true,
+                        enumerable: true,
+                        configurable: true,
+                    });
+                // Different spellings use small reference proxies. Their equivalent
+                // target is copied and normalized once under this pointer identity.
+                walk.schema(schemas[targetKey]);
+            }
+            return alias;
+        };
+        const walk = swaggerSchemaVisitor((value) => {
+            for (const key of ["$ref", "$recursiveRef"])
+                if (typeof value[key] === "string")
+                    value[key] = reference(value[key]);
+        }, () => { });
+        // Snapshot the author-written schemas. The reference walker visits each
+        // newly added alias itself, so additions never invalidate this iteration.
+        walk.document(prepared);
+    }
+    const document = utils_1.OpenApiConverter.upgradeDocument(prepared);
+    const literals = new WeakMap();
+    swaggerSchemaVisitor(() => { }, (_value, holder, key) => {
+        if (!Object.hasOwn(holder, key))
+            return;
+        let keys = literals.get(holder);
+        if (keys === undefined) {
+            keys = new Set();
+            literals.set(holder, keys);
+        }
+        keys.add(key);
+    }).document(document);
+    return {
+        document,
+        isLiteral: (holder, key) => literals.get(holder)?.has(key) === true,
+        referenceAt: (reference) => {
+            const preserved = references.get(reference);
+            if (preserved === undefined)
+                return {
+                    reference,
+                    target: componentAt((document.components ?? {}), reference),
+                };
+            const schemas = document.components?.schemas;
+            return {
+                reference: preserved.reference,
+                target: preserved.pointer !== undefined &&
+                    schemas !== undefined &&
+                    Object.hasOwn(schemas, preserved.key) &&
+                    schemas[preserved.key] !== undefined
+                    ? { pointer: preserved.pointer, value: schemas[preserved.key] }
+                    : undefined,
+            };
+        },
+    };
+};
 exports.normalizeSwaggerDocument = normalizeSwaggerDocument;
+/**
+ * Visits schema holders once per object and reports literal holder slots.
+ *
+ * Literalness belongs to a position: one YAML object can also be a schema at
+ * another position. Retaining holder/key pairs preserves that distinction. This
+ * visitor does not rewrite data, expand references or load documents; its
+ * callbacks own those operations and each walk owns its identity sets.
+ */
+const swaggerSchemaVisitor = (visitSchema, visitLiteral) => {
+    const visited = new WeakSet();
+    const extensions = (value, hasAdditionalOperations = false) => {
+        for (const [key, child] of Object.entries(value))
+            if (key.startsWith("x-") &&
+                !(hasAdditionalOperations && key === "x-additionalOperations"))
+                visitLiteral(child, value, key);
+    };
+    const schema = (value) => {
+        if (value === null || typeof value !== "object" || visited.has(value))
+            return;
+        visited.add(value);
+        visitSchema(value);
+        for (const key of ["example", "examples", "default", "const", "enum"])
+            visitLiteral(value[key], value, key);
+        extensions(value);
+        for (const key of [
+            "properties",
+            "patternProperties",
+            "$defs",
+            "definitions",
+        ])
+            for (const child of Object.values(value[key] ?? {}))
+                schema(child);
+        for (const key of ["oneOf", "anyOf", "allOf", "prefixItems"])
+            if (Array.isArray(value[key]))
+                value[key].forEach(schema);
+        for (const key of [
+            "items",
+            "additionalItems",
+            "additionalProperties",
+            "not",
+            "contains",
+            "if",
+            "then",
+            "else",
+            "propertyNames",
+        ])
+            if (Array.isArray(value[key]))
+                value[key].forEach(schema);
+            else
+                schema(value[key]);
+        for (const child of Object.values(value.dependentSchemas ?? {}))
+            schema(child);
+    };
+    const examples = (value) => {
+        for (const example of Object.values(value ?? {})) {
+            if (example === null || typeof example !== "object")
+                continue;
+            visitLiteral(example.value, example, "value");
+            extensions(example);
+        }
+    };
+    const parameter = (value) => {
+        if (value === null || typeof value !== "object")
+            return;
+        schema(value.schema);
+        content(value.content);
+        visitLiteral(value.example, value, "example");
+        examples(value.examples);
+        extensions(value);
+    };
+    const content = (value) => {
+        for (const media of Object.values(value ?? {})) {
+            if (media === null || typeof media !== "object")
+                continue;
+            schema(media.schema);
+            schema(media.itemSchema);
+            visitLiteral(media.example, media, "example");
+            examples(media.examples);
+            extensions(media);
+        }
+    };
+    const body = (value) => {
+        if (value === null || typeof value !== "object")
+            return;
+        content(value.content);
+        for (const header of Object.values(value.headers ?? {}))
+            parameter(header);
+        extensions(value);
+    };
+    const paths = new WeakSet();
+    const pathItem = (value) => {
+        if (value === null || typeof value !== "object" || paths.has(value))
+            return;
+        paths.add(value);
+        extensions(value, true);
+        if (Array.isArray(value.parameters))
+            value.parameters.forEach(parameter);
+        const operations = [
+            ...[
+                "get",
+                "put",
+                "post",
+                "delete",
+                "options",
+                "head",
+                "patch",
+                "trace",
+                "query",
+            ].map((key) => value[key]),
+            ...Object.values(value.additionalOperations ?? {}),
+            ...Object.values(value["x-additionalOperations"] ?? {}),
+        ];
+        for (const operation of operations) {
+            if (operation === null || typeof operation !== "object")
+                continue;
+            if (Array.isArray(operation.parameters))
+                operation.parameters.forEach(parameter);
+            body(operation.requestBody);
+            for (const response of Object.values(operation.responses ?? {}))
+                body(response);
+            for (const callback of Object.values(operation.callbacks ?? {}))
+                for (const child of Object.values(callback ?? {}))
+                    pathItem(child);
+            extensions(operation);
+        }
+    };
+    return {
+        schema,
+        document: (value) => {
+            const components = value.components ?? {};
+            Object.values(components.schemas ?? {}).forEach(schema);
+            for (const key of ["parameters", "headers"])
+                Object.values(components[key] ?? {}).forEach(parameter);
+            for (const key of ["requestBodies", "responses"])
+                Object.values(components[key] ?? {}).forEach(body);
+            examples(components.examples);
+            for (const group of [value.paths, value.webhooks, components.pathItems])
+                Object.values(group ?? {}).forEach(pathItem);
+        },
+    };
+};

package/lib/structures/ITtscEvidenceDocumentedConfig.d.ts

@@ -1,16 +1,24 @@
-import type { TtscEvidenceGraphTypeScriptSymbol } from "../typings/TtscEvidenceGraphTypeScriptSymbol";
+import type { TtscEvidenceGraphTypeScriptSymbol } from "./TtscEvidenceGraphTypeScriptSymbol";
 /**
  * Options of the `evidence/documented` rule.
  *
  * The rule requires a JSDoc block on every selected export, because a JSDoc
- * block is the only place an `@evidence` tag is ever read from. A symbol
- * without one cannot cite anything: the citation has no location to live in,
- * and the graph's obligation silently shifts onto whichever sibling does have a
- * block.
+ * block is the only place a TypeScript declaration's `@evidence` tag is ever
+ * read from. A symbol without one cannot cite anything: the citation has no
+ * location to live in. Ordinary coverage can still be satisfied by another
+ * host, while a checklist keeps that undocumented host's own obligations
+ * outstanding.
  *
- * Presence is the whole check. The rule never judges what the prose says, how
- * long it is, or whether it is sincere — a rule that tried would only teach
- * authors to write filler that satisfies it.
+ * A block with any text passes, and an empty block is reported like a missing
+ * one with its own message. Beyond that the rule never judges what the prose
+ * says, how long it is, or whether it is sincere, because a rule that tried
+ * would only teach authors to write filler that satisfies it.
+ *
+ * @evidence contracts/common.md#principled-implementation The optional single-or-array symbol selector represents the same supported declaration kinds used by graph hosts; absence delegates to the documented rule's widest default.
+ * @evidence contracts/common.md#clear-and-simple-design This rule has one selection option and reuses the shared symbol union rather than maintaining another vocabulary.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Selection is by declaration kind, with no consumer exceptions or prose-length trick presented as documentation quality.
+ * @evidence contracts/common.md#meaningful-documentation The comment states that a block with text is the entire mechanical check, with an empty block reported separately, and explains the selector's default and cardinality separately from the acknowledgment tags.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type describes rule options and names no path, file, filesystem or process.
  */
 export interface ITtscEvidenceDocumentedConfig {
     /**

package/lib/structures/ITtscEvidenceGraphClaim.d.ts

@@ -10,5 +10,11 @@ import type { ITtscEvidenceGraphTypeScriptClaim } from "./ITtscEvidenceGraphType
  * be acknowledged completely. Separate claims remain separate obligations,
  * preventing two teams' partial use of the same evidence from being reported as
  * one complete use.
+ *
+ * @evidence contracts/common.md#principled-implementation The discriminated union includes exactly the three artifact kinds that can host acknowledgments; Swagger operations remain reference-only.
+ * @evidence contracts/common.md#clear-and-simple-design Each artifact-specific interface owns its selector while the common base owns outgoing coverage, so callers narrow one type discriminator.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The alternatives describe supported artifact semantics and contain no consumer-specific variant or test-only escape.
+ * @evidence contracts/common.md#meaningful-documentation The JSDoc explains the outgoing relationship and independent obligations rather than repeating the union members, with prose separated from tags.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This union only selects among the artifact claim shapes and names no path, file, filesystem or process itself.
  */
 export type ITtscEvidenceGraphClaim = ITtscEvidenceGraphMarkdownClaim | ITtscEvidenceGraphPrismaClaim | ITtscEvidenceGraphTypeScriptClaim;

package/lib/structures/ITtscEvidenceGraphClaimBase.d.ts

@@ -10,8 +10,14 @@ import type { ITtscEvidenceGraphReference } from "./ITtscEvidenceGraphReference"
  * kinds are a property of the language rather than of the claim.
  *
  * Swagger is deliberately absent. An API operation grounds a claim but cannot
- * host `@evidence`, so it extends {@link ITtscEvidenceGraphReferenceBase}
- * instead and never this one.
+ * host `@evidence`, so it belongs to {@link ITtscEvidenceGraphReference} instead
+ * and never this one.
+ *
+ * @evidence contracts/common.md#principled-implementation The generic artifact discriminator preserves each derived claim's kind while shared fields express population ownership, diagnostic inheritance and independently complete references.
+ * @evidence contracts/common.md#clear-and-simple-design Fields common to all claiming artifacts have one owner here; each derived interface supplies only its artifact-specific selection semantics.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Disabled claims and exclusion carriers are explicit supported configuration mechanisms, not hidden consumer-specific coverage substitutions.
+ * @evidence contracts/common.md#meaningful-documentation Member comments explain defaults, glob ordering, root identity and exclusion restrictions with blank lines between documented members and before the tags.
+ * @evidence contracts/portability.md#os-neutral-implementation Root and file patterns describe a native filesystem boundary with stable absolute or project-relative roots, portable glob separators and explicit rejection of Windows drive-relative paths; identity case sensitivity is a graph policy, not an inferred filesystem capability.
  */
 export interface ITtscEvidenceGraphClaimBase<Type extends string> {
     /** Identifies the artifact kind making this claim. */

package/lib/structures/ITtscEvidenceGraphConfig.d.ts

@@ -7,6 +7,12 @@ import type { ITtscEvidenceGraphClaim } from "./ITtscEvidenceGraphClaim";
  * evidence it must cite with a reason. The configuration defines those
  * boundaries without hardcoding a repository's folder layout or its notion of
  * proof.
+ *
+ * @evidence contracts/common.md#principled-implementation A graph is represented by independent claims, each carrying its own references, so the type preserves the boundary at which coverage is evaluated.
+ * @evidence contracts/common.md#clear-and-simple-design The root holds only the claim collection; population and policy decisions stay in claim and reference types.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts No repository-specific path, expected coverage result or bypass flag is embedded in this root representation.
+ * @evidence contracts/common.md#meaningful-documentation The root and claims comments explain relationship direction, independent coverage and the nonempty-array runtime requirement that TypeScript's array type cannot enforce.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This type holds a list of claims and names no path, file, filesystem or process itself.
  */
 export interface ITtscEvidenceGraphConfig {
     /**

package/lib/structures/ITtscEvidenceGraphMarkdownClaim.d.ts

@@ -1,5 +1,5 @@
-import type { TtscEvidenceGraphMarkdownSymbol } from "../typings/TtscEvidenceGraphMarkdownSymbol";
 import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase";
+import type { TtscEvidenceGraphMarkdownSymbol } from "./TtscEvidenceGraphMarkdownSymbol";
 /**
  * A population of Markdown documents claiming its referenced evidence.
  *
@@ -15,6 +15,12 @@ import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase"
  *
  * @example
  *   <!-- @evidence docs/orders.md#create-order This section adopts the creation contract. -->
+ *
+ * @evidence contracts/common.md#principled-implementation The Markdown discriminator and outline-kind selector express which parsed document scopes can make claims while coverage policy remains on their references.
+ * @evidence contracts/common.md#clear-and-simple-design Only Markdown files and host kinds are specialized; the shared base remains responsible for roots, diagnostics and outgoing references.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The type selects outline kinds rather than hardcoding document names or accepting a fixture-specific acknowledgment path.
+ * @evidence contracts/common.md#meaningful-documentation The comment describes where Markdown acknowledgments live and the member comments state file parsing and selector defaults, separated from these tags.
+ * @evidence contracts/portability.md#os-neutral-implementation The inherited stable root and ordered glob paths select a native document population independently of outline targets; separators are portable and identity remains the explicit graph policy rather than a guess from the OS name.
  */
 export interface ITtscEvidenceGraphMarkdownClaim extends ITtscEvidenceGraphClaimBase<"markdown"> {
     /**

package/lib/structures/ITtscEvidenceGraphMarkdownReference.d.ts

@@ -1,5 +1,5 @@
-import type { TtscEvidenceGraphMarkdownSymbol } from "../typings/TtscEvidenceGraphMarkdownSymbol";
 import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphReferenceBase";
+import type { TtscEvidenceGraphMarkdownSymbol } from "./TtscEvidenceGraphMarkdownSymbol";
 /**
  * A population of documentary evidence that the owning claim must cite.
  *
@@ -8,6 +8,12 @@ import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphRefere
  * while allowing one file or heading target to acknowledge its selected
  * descendants. Citations remain anchored in the outline, so an editorial change
  * cannot silently preserve a claim whose grounds disappeared.
+ *
+ * @evidence contracts/common.md#principled-implementation The Markdown discriminator and heading selector describe outline evidence; the checklist flag adds a per-host obligation rather than changing how a heading target is identified.
+ * @evidence contracts/common.md#clear-and-simple-design Markdown population and checklist details stay together while ordinary reference policies remain inherited from the shared base.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Checklist mode explicitly rejects aggregate positive citations and incompatible cardinality policies instead of allowing one answer to impersonate every item's answer.
+ * @evidence contracts/common.md#meaningful-documentation Separate property paragraphs explain rooted addresses, ordered glob selection, checklist denominator, exclusion behavior and policy incompatibilities without relying on these tags as instructions.
+ * @evidence contracts/portability.md#os-neutral-implementation Root describes a stable native directory including links and junctions, while evidence addresses use root-relative protocol spelling; drive-relative paths are refused and graph identity does not guess host filesystem case rules.
  */
 export interface ITtscEvidenceGraphMarkdownReference extends ITtscEvidenceGraphReferenceBase<"markdown"> {
     /**

package/lib/structures/ITtscEvidenceGraphPrismaClaim.d.ts

@@ -1,5 +1,5 @@
-import type { TtscEvidenceGraphPrismaSymbol } from "../typings/TtscEvidenceGraphPrismaSymbol";
 import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase";
+import type { TtscEvidenceGraphPrismaSymbol } from "./TtscEvidenceGraphPrismaSymbol";
 /**
  * A Prisma schema claiming its referenced evidence.
  *
@@ -38,6 +38,12 @@ import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase"
  *   coupon_limit Int
  * }
  * ```
+ *
+ * @evidence contracts/common.md#principled-implementation The Prisma discriminator and semantic model/column/relation selector match parser-classified schema units, including file-level exclusion carriers that deliberately have no model identity.
+ * @evidence contracts/common.md#clear-and-simple-design Prisma specializes only schema-file interpretation and host kinds while the common base carries root and outgoing coverage policy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Eligibility is based on actual schema documentation syntax; ignored double-slash annotations do not silently become evidence and no consumer model is singled out.
+ * @evidence contracts/common.md#meaningful-documentation The declaration documents comment attachment, file-level exclusions and native Prisma examples; field comments explain schema composition and selector defaults.
+ * @evidence contracts/portability.md#os-neutral-implementation Schema files resolve through the inherited stable native root while prisma model identities remain path-free; linked aliases join one schema without using OS names to infer file case or capability.
  */
 export interface ITtscEvidenceGraphPrismaClaim extends ITtscEvidenceGraphClaimBase<"prisma"> {
     /**

package/lib/structures/ITtscEvidenceGraphPrismaReference.d.ts

@@ -1,5 +1,5 @@
-import type { TtscEvidenceGraphPrismaSymbol } from "../typings/TtscEvidenceGraphPrismaSymbol";
 import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphReferenceBase";
+import type { TtscEvidenceGraphPrismaSymbol } from "./TtscEvidenceGraphPrismaSymbol";
 /**
  * A population of Prisma schema declarations that the owning claim must cite.
  *
@@ -12,6 +12,12 @@ import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphRefere
  * folder is a single namespace whose files reference each other. The parse is
  * Prisma's own, so a schema it rejects is reported as a parse failure rather
  * than as an empty population.
+ *
+ * @evidence contracts/common.md#principled-implementation This representation selects models and parser-classified members from one composed schema, preserving Prisma's cross-file namespace rather than treating each file as an independent schema.
+ * @evidence contracts/common.md#clear-and-simple-design Root, files and symbol choices define the Prisma population while shared acknowledgment policies stay in the base reference.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Parsing failures remain failures rather than an empty-success substitute, and model-only default selection is an explicit general contract rather than a consumer exception.
+ * @evidence contracts/common.md#meaningful-documentation Member prose explains schema-set identity, root effects, default model granularity and aggregate member coverage with separated documentation blocks.
+ * @evidence contracts/portability.md#os-neutral-implementation Root selects a native schema directory independently of path-free prisma targets; stable relative or absolute paths and linked directories are supported while drive-relative Windows paths are explicitly invalid.
  */
 export interface ITtscEvidenceGraphPrismaReference extends ITtscEvidenceGraphReferenceBase<"prisma"> {
     /**

package/lib/structures/ITtscEvidenceGraphReference.d.ts

@@ -6,9 +6,15 @@ import type { ITtscEvidenceGraphTypeScriptReference } from "./ITtscEvidenceGraph
  * One population of evidence units that a claim must cite completely.
  *
  * A reference selects what counts as evidence: Markdown documents and heading
- * sections, Swagger or OpenAPI operations, or selected exported TypeScript
- * symbols. Every unit it materializes must be acknowledged by the owning claim,
- * so a reference is the denominator of one coverage obligation, never a pooled
- * global set.
+ * sections, Prisma schema declarations, Swagger or OpenAPI operations, or
+ * selected exported TypeScript symbols. Every unit it materializes must be
+ * acknowledged by the owning claim, so a reference is the denominator of one
+ * coverage obligation, never a pooled global set.
+ *
+ * @evidence contracts/common.md#principled-implementation The union permits each supported evidence artifact, including reference-only Swagger operations, and retains each kind's population contract.
+ * @evidence contracts/common.md#clear-and-simple-design Artifact-specific interfaces share one policy base, keeping selection details with their parser rather than introducing a second configuration hierarchy.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The closed alternatives reflect supported loaders rather than consumer names or fixture-specific bypasses.
+ * @evidence contracts/common.md#meaningful-documentation The native comment explains reference ownership and the coverage denominator; member-specific selection details remain in their respective declarations.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation This union only selects among the artifact reference shapes and names no path, file, filesystem or process itself.
  */
 export type ITtscEvidenceGraphReference = ITtscEvidenceGraphMarkdownReference | ITtscEvidenceGraphPrismaReference | ITtscEvidenceGraphSwaggerReference | ITtscEvidenceGraphTypeScriptReference;

package/lib/structures/ITtscEvidenceGraphReferenceBase.d.ts

@@ -22,6 +22,12 @@ import type { TtscLintSeverity } from "@ttsc/lint";
  * these. They tighten a count inside the per-reference obligation; that one
  * gives the obligation a host dimension, and it is documented on the Markdown
  * reference because no other artifact kind is read item by item.
+ *
+ * @evidence contracts/common.md#principled-implementation Optional policy fields independently constrain one reference relation, preserving inherited severity and permissive zero-value semantics without pooling sibling obligations.
+ * @evidence contracts/common.md#clear-and-simple-design One generic base owns shared acknowledgment policies while artifact-specific references own their populations and Markdown alone owns checklist semantics.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts These explicit policies constrain real graph relations; requireReview documents its limited assurance instead of claiming a fingerprint proves review sincerity.
+ * @evidence contracts/common.md#meaningful-documentation Property comments explain counting identities, aggregate scopes, expiry and the limitations of review fingerprints; separate paragraphs and member gaps keep distinct requirements readable.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation These shared fields are policies and selectors over evidence units and name no path, file, filesystem or process.
  */
 export interface ITtscEvidenceGraphReferenceBase<Type extends string> {
     /** Identifies the artifact kind this population materializes. */

package/lib/structures/ITtscEvidenceGraphSwaggerReference.d.ts

@@ -7,6 +7,12 @@ import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphRefere
  * TypeScript or Markdown claim, but a Swagger document cannot host `@evidence`
  * declarations. Every operation under the normalized document's `paths` object
  * becomes one independent evidence unit.
+ *
+ * @evidence contracts/common.md#principled-implementation A Swagger reference identifies one normalized API document and inherits reference policies; absence of a Swagger claim counterpart reflects that operations cannot host acknowledgments.
+ * @evidence contracts/common.md#clear-and-simple-design One exact source location is sufficient because document format normalization and operation indexing belong to the loader, not to extra configuration layers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts An unavailable remote source fails its obligation rather than silently removing API operations from the expected population.
+ * @evidence contracts/common.md#meaningful-documentation The source comment explains accepted local and HTTP locations, rejection of unstable drive-relative paths, normalization and operation-target spelling.
+ * @evidence contracts/portability.md#os-neutral-implementation The file field distinguishes native local paths from HTTP URLs, requiring stable project-relative or absolute local resolution and refusing Windows drive-relative spelling instead of applying filesystem rules to a URL.
  */
 export interface ITtscEvidenceGraphSwaggerReference extends ITtscEvidenceGraphReferenceBase<"swagger"> {
     /**

package/lib/structures/ITtscEvidenceGraphTypeScriptClaim.d.ts

@@ -1,5 +1,5 @@
-import type { TtscEvidenceGraphTypeScriptSymbol } from "../typings/TtscEvidenceGraphTypeScriptSymbol";
 import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase";
+import type { TtscEvidenceGraphTypeScriptSymbol } from "./TtscEvidenceGraphTypeScriptSymbol";
 /**
  * A population of TypeScript declarations claiming its referenced evidence.
  *
@@ -14,6 +14,12 @@ import type { ITtscEvidenceGraphClaimBase } from "./ITtscEvidenceGraphClaimBase"
  * a host selected by {@link symbol}. An exclusion may instead sit on any
  * supported public export in the matching {@link files}, without changing the
  * target scope this claim excludes.
+ *
+ * @evidence contracts/common.md#principled-implementation The literal TypeScript discriminator and shared symbol vocabulary describe public Program declarations; root and files narrow that Program rather than promising a disk loader for claims.
+ * @evidence contracts/common.md#clear-and-simple-design This interface specializes the common claim with only TypeScript population and host selection details, retaining reference ownership in the base.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Host and exclusion eligibility follow supported declaration syntax and configured populations rather than special cases for known consumers.
+ * @evidence contracts/common.md#meaningful-documentation The JSDoc explicitly distinguishes Program inclusion from rooted path selection and explains host versus exclusion-carrier eligibility and selector defaults.
+ * @evidence contracts/portability.md#os-neutral-implementation Root and glob spelling describe the native project boundary used to match Program sources; selection must respect host-supplied source identity and linked paths rather than inferring filesystem case policy from an operating-system name.
  */
 export interface ITtscEvidenceGraphTypeScriptClaim extends ITtscEvidenceGraphClaimBase<"typescript"> {
     /**

package/lib/structures/ITtscEvidenceGraphTypeScriptReference.d.ts

@@ -1,5 +1,5 @@
-import type { TtscEvidenceGraphTypeScriptSymbol } from "../typings/TtscEvidenceGraphTypeScriptSymbol";
 import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphReferenceBase";
+import type { TtscEvidenceGraphTypeScriptSymbol } from "./TtscEvidenceGraphTypeScriptSymbol";
 /**
  * A population of TypeScript evidence that the owning claim must cite.
  *
@@ -11,6 +11,12 @@ import type { ITtscEvidenceGraphReferenceBase } from "./ITtscEvidenceGraphRefere
  * The selection keeps the evidence graph deliberate. It can cover public types
  * by default, then opt into functions or properties only where their individual
  * contracts deserve documentary proof.
+ *
+ * @evidence contracts/common.md#principled-implementation Local Program, explicit root and installed-package populations share one reference policy while documenting their distinct loading boundaries and exported-symbol identities.
+ * @evidence contracts/common.md#clear-and-simple-design Package and root selection remain explicit alternatives within one artifact interface; the shared base owns policy instead of duplicating it for each loading mode.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Package lookup uses declaration entry semantics, not a consumer-specific JavaScript entry or a fallback that invents unavailable exports.
+ * @evidence contracts/common.md#meaningful-documentation Property prose explains the root/package restriction, declaration-entry precedence, Program snapshot priority and exact selector defaults with separate member comments.
+ * @evidence contracts/portability.md#os-neutral-implementation The type distinguishes a native root or installed-package location from exported symbol identity; forward-slash glob semantics are explicit while path resolution and linked-directory identity remain the loader's supported filesystem boundary.
  */
 export interface ITtscEvidenceGraphTypeScriptReference extends ITtscEvidenceGraphReferenceBase<"typescript"> {
     /**
@@ -42,8 +48,10 @@ export interface ITtscEvidenceGraphTypeScriptReference extends ITtscEvidenceGrap
      * addressed by its accessor path from that entry — which is what makes
      * `api.functional.questions.get` nameable. The entry is read from the `types`
      * condition of the `exports` map, then `typesVersions`, then the `types` or
-     * `typings` field — never `main`, which names the JavaScript a consumer runs
-     * rather than the declarations a citation can address.
+     * `typings` field. If no declaration channel answers, a runtime `exports`
+     * target or `main` is accepted only when it names TypeScript source itself,
+     * as in a source-first workspace package. Emitted JavaScript entries are not
+     * declaration populations.
      */
     package?: string;
     /**