@gate-forge/core 0.1.0

package/dist/graph/schema.d.ts

@@ -0,0 +1,448 @@
+/**
+ * Resource-graph input/output schemas (Phase 1 "resource graph
+ * construction"). The graph consumes detector contributions — the
+ * discovery-spike output shape pinned by GPP/3 (`resources`,
+ * `unresolved`, `findings`) plus detector provenance — and produces the
+ * normalized, deterministically ordered graph the policy engine and
+ * verdict engine speak.
+ *
+ * ADR 0001 encoded here:
+ * - D5.3: resource ids are plane-qualified `plane.name`; `source`
+ *   paths are normalized repo-root-relative (discovery-spike
+ *   limitation 5: spike ids embed command-line-relative paths);
+ * - D1: `unresolved` entries stay first-class and gate-visible;
+ * - invariant 9: references to removed/renamed resources surface as
+ *   typed `stale` entries, never silent disappearance.
+ */
+import { z } from 'zod';
+/**
+ * Canonical detector attribute vocabulary (camelCase). The graph reads
+ * `resourceName` as THE identity attribute of every resource; detectors
+ * set it to the table name for table kinds. Class-symbol resources
+ * additionally use the attribute keys declared in
+ * {@link ClassSymbolAttributesSchema}.
+ */
+export declare const RESOURCE_NAME_ATTRIBUTE = "resourceName";
+/**
+ * Reserved resource `kind` marking a class-symbol declaration used by
+ * the graph's symbol table for cross-module inheritance resolution
+ * (go/no-go first action #2). Detectors emit one per table candidate
+ * class whose identity the graph may need to resolve through base
+ * classes; these resources are consumed by the symbol table and are
+ * NOT emitted as business resources.
+ */
+export declare const CLASS_SYMBOL_KIND = "gateforge.class";
+/**
+ * Evidence-only resource kinds beyond the class-symbol channel (ADR 0004
+ * D1). Resources of these kinds are consumed by the engine's endpoint
+ * compiler, never emitted as business resources, and never classified —
+ * keeping route facts out of the business-identity namespace (the
+ * route/table collision red probe). This set is ENGINE-OWNED and closed:
+ * a detector cannot invent a new evidence-only kind or flag arbitrary
+ * resources out of classification, because that would be a
+ * detector-controlled suppressive-authority leak.
+ */
+export declare const EVIDENCE_ONLY_RESOURCE_KINDS: readonly string[];
+/**
+ * Resource `kind` the engine's endpoint compiler emits for joined
+ * endpoints (ADR 0004 D1/D5). Endpoints ARE classified and carry their
+ * own HTTP obligations, but `crud:*`/`persistence:*` contracts never
+ * generate against them: CRUD state flows through the LINKED business
+ * resource's own obligations — routes are never conflated with tables.
+ * Mirrors `HTTP_ENDPOINT_KIND` in `@gate-forge/http-contract` (core cannot
+ * depend on it); keep the two in lockstep.
+ */
+export declare const HTTP_ENDPOINT_RESOURCE_KIND = "http.endpoint";
+/** True when a raw resource kind is engine-owned evidence-only. */
+export declare function isEvidenceOnlyKind(kind: string): boolean;
+/** Attribute payload of a {@link CLASS_SYMBOL_KIND} resource. */
+export declare const ClassSymbolAttributesSchema: z.ZodObject<{
+    qname: z.ZodString;
+    resourceKind: z.ZodString;
+    baseNames: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tableName: z.ZodOptional<z.ZodString>;
+    abstract: z.ZodOptional<z.ZodBoolean>;
+    tablenameUnresolved: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Inferred class-symbol attribute shape. */
+export type ClassSymbolAttributes = z.infer<typeof ClassSymbolAttributesSchema>;
+/**
+ * Detector finding (discovery-spike lineage, e.g.
+ * `DUPLICATE_TABLE_NAME`): a non-resource observation about the
+ * scanned sources. This is the canonical home of the shape;
+ * `@gate-forge/plugin-protocol` carries a wire-compatible copy.
+ */
+export declare const FindingSchema: z.ZodObject<{
+    code: z.ZodString;
+    detail: z.ZodString;
+    locations: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Inferred finding shape. */
+export type Finding = z.infer<typeof FindingSchema>;
+/**
+ * A finding with provenance: graph-issued findings use `gateforge.graph`.
+ */
+export declare const GraphFindingSchema: z.ZodObject<{
+    code: z.ZodString;
+    detail: z.ZodString;
+    locations: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>>;
+    detectorId: z.ZodString;
+}, z.core.$strict>;
+/** Inferred graph-finding shape. */
+export type GraphFinding = z.infer<typeof GraphFindingSchema>;
+/**
+ * One detector's contribution to the graph: its pinned identity plus
+ * the discovery-spike output shape. `resources` entries are validated
+ * individually by the graph — invalid entries become `INVALID_RESOURCE`
+ * findings instead of aborting the run (fail visible, never crash).
+ *
+ * Since GPP/3 (ADR 0003 D6) every contribution also carries
+ * `classificationSignals` — the GPP/2 discovery shape is rejected
+ * fail-closed with an actionable diagnostic naming the missing field.
+ */
+export declare const DetectorOutputSchema: z.ZodObject<{
+    detectorId: z.ZodString;
+    detectorVersion: z.ZodString;
+    resources: z.ZodArray<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        id: z.ZodString;
+        kind: z.ZodString;
+        source: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+        detectorVersion: z.ZodString;
+        attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>;
+    unresolved: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        detail: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    findings: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        detail: z.ZodString;
+        locations: z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    classificationSignals: z.ZodArray<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        target: z.ZodObject<{
+            resourceName: z.ZodOptional<z.ZodString>;
+            resourceId: z.ZodOptional<z.ZodString>;
+            symbol: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        dimension: z.ZodEnum<{
+            exposure: "exposure";
+            plane: "plane";
+            identity: "identity";
+            "lifecycle.create": "lifecycle.create";
+            "lifecycle.read": "lifecycle.read";
+            "lifecycle.update": "lifecycle.update";
+            "lifecycle.delete": "lifecycle.delete";
+            "delete-semantics": "delete-semantics";
+            "archive-state": "archive-state";
+            "adapter-binding": "adapter-binding";
+            internality: "internality";
+        }>;
+        assertion: z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodString>, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>;
+        basis: z.ZodEnum<{
+            "code-positive": "code-positive";
+            "code-negative-closed-world": "code-negative-closed-world";
+            declaration: "declaration";
+            "organization-policy": "organization-policy";
+        }>;
+        source: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+        detector: z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    scannedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** Inferred detector-contribution shape. */
+export type DetectorOutput = z.infer<typeof DetectorOutputSchema>;
+/**
+ * Everything the graph ingests: one or more detector contributions and
+ * the artifact populations stale-reference validation watches
+ * (invariant 9 / GF-06). Since the automatic-classification cutover
+ * (plan phase 5, ADR 0003 D5) the graph binds NO business meaning —
+ * business meaning comes only from the deterministic classifier
+ * (`runClassification`) over detector signals; the manual
+ * classifications document no longer exists.
+ *
+ * `claims` and `waivers` are deliberately typed `unknown`-tolerant: the
+ * graph validates each entry individually and converts invalid ones
+ * into `INVALID_CLAIM`/`INVALID_WAIVER` findings instead of aborting
+ * the run (fail visible, never crash).
+ */
+export interface ResourceGraphInput {
+    /** Detector contributions; ≥1. */
+    detectors: DetectorOutput[];
+    /** Claims to watch for stale references (obligation ids). */
+    claims?: unknown[];
+    /** Adapter file names or paths (`.gateforge/adapters/<resourceId>.mjs`). */
+    adapters?: string[];
+    /** Waivers to watch for stale references (exact-scope resourceIds). */
+    waivers?: unknown[];
+}
+/**
+ * A normalized graph resource. `id` is the plane-qualified `plane.name`
+ * identity (D5.3); it is `null` while the resource is unclassified and
+ * no plane could be derived. `classification`/`exposure` are `null`
+ * until a classification entry binds the resource. Class-symbol
+ * resources never appear here (consumed by the symbol table).
+ */
+export declare const GraphResourceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodNullable<z.ZodString>;
+    name: z.ZodString;
+    plane: z.ZodNullable<z.ZodEnum<{
+        tenant: "tenant";
+        master: "master";
+        global: "global";
+    }>>;
+    kind: z.ZodString;
+    source: z.ZodString;
+    location: z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodNumber;
+        col: z.ZodNumber;
+    }, z.core.$strict>;
+    exposure: z.ZodNullable<z.ZodEnum<{
+        "user-facing": "user-facing";
+        internal: "internal";
+    }>>;
+    classification: z.ZodNullable<z.ZodObject<{
+        exposure: z.ZodEnum<{
+            "user-facing": "user-facing";
+            internal: "internal";
+        }>;
+        plane: z.ZodEnum<{
+            tenant: "tenant";
+            master: "master";
+            global: "global";
+        }>;
+        lifecycle: z.ZodObject<{
+            create: z.ZodBoolean;
+            read: z.ZodBoolean;
+            update: z.ZodBoolean;
+            delete: z.ZodBoolean;
+            deleteSemantics: z.ZodOptional<z.ZodEnum<{
+                hard: "hard";
+                archive: "archive";
+            }>>;
+            archiveFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+            updateableFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        primaryKey: z.ZodArray<z.ZodString>;
+        evidenceAdapter: z.ZodOptional<z.ZodString>;
+        evidenceLane: z.ZodOptional<z.ZodEnum<{
+            adapter: "adapter";
+            claims: "claims";
+        }>>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    classificationTrace: z.ZodNullable<z.ZodObject<{
+        rules: z.ZodArray<z.ZodString>;
+        defaultsApplied: z.ZodArray<z.ZodString>;
+        contributingSignalIds: z.ZodArray<z.ZodString>;
+        contributingDetectors: z.ZodArray<z.ZodString>;
+        contradictions: z.ZodArray<z.ZodObject<{
+            dimension: z.ZodString;
+            detail: z.ZodString;
+            locations: z.ZodArray<z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                col: z.ZodNumber;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        unresolvedDimensions: z.ZodArray<z.ZodString>;
+        decisionFingerprint: z.ZodString;
+    }, z.core.$strict>>;
+    detector: z.ZodObject<{
+        id: z.ZodString;
+        version: z.ZodString;
+    }, z.core.$strict>;
+    attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+/** Inferred normalized-resource shape. */
+export type GraphResource = z.infer<typeof GraphResourceSchema>;
+/** One gate-visible unresolved entry with its detector provenance. */
+export declare const GraphUnresolvedSchema: z.ZodObject<{
+    reason: z.ZodObject<{
+        code: z.ZodString;
+        detail: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    detectorId: z.ZodString;
+    detectorVersion: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+/** Inferred graph-unresolved shape. */
+export type GraphUnresolved = z.infer<typeof GraphUnresolvedSchema>;
+/** Artifact kinds stale-reference validation watches (invariant 9). */
+export declare const StaleReferenceKindSchema: z.ZodEnum<{
+    adapter: "adapter";
+    claim: "claim";
+    waiver: "waiver";
+}>;
+/** Inferred stale-reference-kind shape. */
+export type StaleReferenceKind = z.infer<typeof StaleReferenceKindSchema>;
+/**
+ * A reference to a resource that no longer exists. `reference` is the
+ * stale pointer itself: an obligation id, an adapter name, or a
+ * waiver-scoped resource id.
+ */
+export declare const StaleReferenceSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        adapter: "adapter";
+        claim: "claim";
+        waiver: "waiver";
+    }>;
+    reference: z.ZodString;
+    detail: z.ZodString;
+}, z.core.$strict>;
+/** Inferred stale-reference shape. */
+export type StaleReference = z.infer<typeof StaleReferenceSchema>;
+/**
+ * The built resource graph. Deterministic: every array is sorted by a
+ * total order, so identical inputs serialize byte-for-byte identically
+ * under `canonicalJson`.
+ */
+export declare const ResourceGraphSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    resources: z.ZodArray<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        id: z.ZodNullable<z.ZodString>;
+        name: z.ZodString;
+        plane: z.ZodNullable<z.ZodEnum<{
+            tenant: "tenant";
+            master: "master";
+            global: "global";
+        }>>;
+        kind: z.ZodString;
+        source: z.ZodString;
+        location: z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>;
+        exposure: z.ZodNullable<z.ZodEnum<{
+            "user-facing": "user-facing";
+            internal: "internal";
+        }>>;
+        classification: z.ZodNullable<z.ZodObject<{
+            exposure: z.ZodEnum<{
+                "user-facing": "user-facing";
+                internal: "internal";
+            }>;
+            plane: z.ZodEnum<{
+                tenant: "tenant";
+                master: "master";
+                global: "global";
+            }>;
+            lifecycle: z.ZodObject<{
+                create: z.ZodBoolean;
+                read: z.ZodBoolean;
+                update: z.ZodBoolean;
+                delete: z.ZodBoolean;
+                deleteSemantics: z.ZodOptional<z.ZodEnum<{
+                    hard: "hard";
+                    archive: "archive";
+                }>>;
+                archiveFields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+                updateableFields: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>;
+            primaryKey: z.ZodArray<z.ZodString>;
+            evidenceAdapter: z.ZodOptional<z.ZodString>;
+            evidenceLane: z.ZodOptional<z.ZodEnum<{
+                adapter: "adapter";
+                claims: "claims";
+            }>>;
+            notes: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        classificationTrace: z.ZodNullable<z.ZodObject<{
+            rules: z.ZodArray<z.ZodString>;
+            defaultsApplied: z.ZodArray<z.ZodString>;
+            contributingSignalIds: z.ZodArray<z.ZodString>;
+            contributingDetectors: z.ZodArray<z.ZodString>;
+            contradictions: z.ZodArray<z.ZodObject<{
+                dimension: z.ZodString;
+                detail: z.ZodString;
+                locations: z.ZodArray<z.ZodObject<{
+                    file: z.ZodString;
+                    line: z.ZodNumber;
+                    col: z.ZodNumber;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            unresolvedDimensions: z.ZodArray<z.ZodString>;
+            decisionFingerprint: z.ZodString;
+        }, z.core.$strict>>;
+        detector: z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodString;
+        }, z.core.$strict>;
+        attributes: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>;
+    unresolved: z.ZodArray<z.ZodObject<{
+        reason: z.ZodObject<{
+            code: z.ZodString;
+            detail: z.ZodString;
+            location: z.ZodObject<{
+                file: z.ZodString;
+                line: z.ZodNumber;
+                col: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        detectorId: z.ZodString;
+        detectorVersion: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    findings: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        detail: z.ZodString;
+        locations: z.ZodArray<z.ZodObject<{
+            file: z.ZodString;
+            line: z.ZodNumber;
+            col: z.ZodNumber;
+        }, z.core.$strict>>;
+        detectorId: z.ZodString;
+    }, z.core.$strict>>;
+    stale: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            adapter: "adapter";
+            claim: "claim";
+            waiver: "waiver";
+        }>;
+        reference: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Inferred resource-graph shape. */
+export type ResourceGraph = z.infer<typeof ResourceGraphSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/graph/schema.d.ts.map

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

package/dist/graph/schema.js

@@ -0,0 +1,237 @@
+/**
+ * Resource-graph input/output schemas (Phase 1 "resource graph
+ * construction"). The graph consumes detector contributions — the
+ * discovery-spike output shape pinned by GPP/3 (`resources`,
+ * `unresolved`, `findings`) plus detector provenance — and produces the
+ * normalized, deterministically ordered graph the policy engine and
+ * verdict engine speak.
+ *
+ * ADR 0001 encoded here:
+ * - D5.3: resource ids are plane-qualified `plane.name`; `source`
+ *   paths are normalized repo-root-relative (discovery-spike
+ *   limitation 5: spike ids embed command-line-relative paths);
+ * - D1: `unresolved` entries stay first-class and gate-visible;
+ * - invariant 9: references to removed/renamed resources surface as
+ *   typed `stale` entries, never silent disappearance.
+ */
+import { z } from 'zod';
+import { ExposureSchema, LocationSchema, PlaneSchema, SchemaVersionField } from '../schemas/common.js';
+import { ClassificationSchema } from '../schemas/classification.js';
+import { ClassificationSignalSchema } from '../schemas/classification-signal.js';
+import { ClassificationDecisionTraceSchema } from '../classifier/schema.js';
+import { ResourceSchema } from '../schemas/resource.js';
+import { UnresolvedReasonSchema } from '../schemas/verdict.js';
+/**
+ * Canonical detector attribute vocabulary (camelCase). The graph reads
+ * `resourceName` as THE identity attribute of every resource; detectors
+ * set it to the table name for table kinds. Class-symbol resources
+ * additionally use the attribute keys declared in
+ * {@link ClassSymbolAttributesSchema}.
+ */
+export const RESOURCE_NAME_ATTRIBUTE = 'resourceName';
+/**
+ * Reserved resource `kind` marking a class-symbol declaration used by
+ * the graph's symbol table for cross-module inheritance resolution
+ * (go/no-go first action #2). Detectors emit one per table candidate
+ * class whose identity the graph may need to resolve through base
+ * classes; these resources are consumed by the symbol table and are
+ * NOT emitted as business resources.
+ */
+export const CLASS_SYMBOL_KIND = 'gateforge.class';
+/**
+ * Evidence-only resource kinds beyond the class-symbol channel (ADR 0004
+ * D1). Resources of these kinds are consumed by the engine's endpoint
+ * compiler, never emitted as business resources, and never classified —
+ * keeping route facts out of the business-identity namespace (the
+ * route/table collision red probe). This set is ENGINE-OWNED and closed:
+ * a detector cannot invent a new evidence-only kind or flag arbitrary
+ * resources out of classification, because that would be a
+ * detector-controlled suppressive-authority leak.
+ */
+export const EVIDENCE_ONLY_RESOURCE_KINDS = ['http.contract'];
+/**
+ * Resource `kind` the engine's endpoint compiler emits for joined
+ * endpoints (ADR 0004 D1/D5). Endpoints ARE classified and carry their
+ * own HTTP obligations, but `crud:*`/`persistence:*` contracts never
+ * generate against them: CRUD state flows through the LINKED business
+ * resource's own obligations — routes are never conflated with tables.
+ * Mirrors `HTTP_ENDPOINT_KIND` in `@gate-forge/http-contract` (core cannot
+ * depend on it); keep the two in lockstep.
+ */
+export const HTTP_ENDPOINT_RESOURCE_KIND = 'http.endpoint';
+/** True when a raw resource kind is engine-owned evidence-only. */
+export function isEvidenceOnlyKind(kind) {
+    return kind === CLASS_SYMBOL_KIND || EVIDENCE_ONLY_RESOURCE_KINDS.includes(kind);
+}
+/** Attribute payload of a {@link CLASS_SYMBOL_KIND} resource. */
+export const ClassSymbolAttributesSchema = z
+    .strictObject({
+    /** Scope-qualified class name (dotted), e.g. `pkg.models.Base`. */
+    qname: z.string().min(1),
+    /** `kind` the graph must use for a table materialized from this class. */
+    resourceKind: z.string().min(1),
+    /** Direct base classes as written in source, in declaration order. */
+    baseNames: z.array(z.string().min(1)).optional(),
+    /** Literal `__tablename__` declared on the class itself, if any. */
+    tableName: z.string().min(1).optional(),
+    /** True for `__abstract__ = True` bases (never materialize directly). */
+    abstract: z.boolean().optional(),
+    /**
+     * Detector assertion that this class's tablename is unresolved;
+     * when the symbol table cannot resolve it either, the graph
+     * synthesizes a typed `inherited_tablename_unresolved` entry so
+     * the class never vanishes silently.
+     */
+    tablenameUnresolved: z.boolean().optional(),
+});
+/**
+ * Detector finding (discovery-spike lineage, e.g.
+ * `DUPLICATE_TABLE_NAME`): a non-resource observation about the
+ * scanned sources. This is the canonical home of the shape;
+ * `@gate-forge/plugin-protocol` carries a wire-compatible copy.
+ */
+export const FindingSchema = z
+    .strictObject({
+    /** Short stable finding code, e.g. `DUPLICATE_TABLE_NAME`. */
+    code: z.string().min(1),
+    /** Single-cause human explanation. */
+    detail: z.string().min(1),
+    /** Source locations the finding points at (≥1, deterministically ordered). */
+    locations: z.array(LocationSchema).min(1),
+});
+/**
+ * A finding with provenance: graph-issued findings use `gateforge.graph`.
+ */
+export const GraphFindingSchema = z
+    .strictObject({
+    code: z.string().min(1),
+    detail: z.string().min(1),
+    /**
+     * Source locations the finding points at. Detector findings carry
+     * ≥1 (the pinned shape); graph-issued findings may carry zero when
+     * no single source location applies (e.g. schema-invalid claims).
+     */
+    locations: z.array(LocationSchema),
+    /** Detector that issued the finding. */
+    detectorId: z.string().min(1),
+});
+/**
+ * One detector's contribution to the graph: its pinned identity plus
+ * the discovery-spike output shape. `resources` entries are validated
+ * individually by the graph — invalid entries become `INVALID_RESOURCE`
+ * findings instead of aborting the run (fail visible, never crash).
+ *
+ * Since GPP/3 (ADR 0003 D6) every contribution also carries
+ * `classificationSignals` — the GPP/2 discovery shape is rejected
+ * fail-closed with an actionable diagnostic naming the missing field.
+ */
+export const DetectorOutputSchema = z
+    .strictObject({
+    /** Plugin id pinned at the GPP/3 handshake (or in-process loader). */
+    detectorId: z.string().min(1),
+    /** Plugin version pinned at the handshake. */
+    detectorVersion: z.string().min(1),
+    /** Discovered resources (frozen core `Resource` shape). */
+    resources: z.array(ResourceSchema),
+    /** Typed reasons parts of the input could not be resolved. */
+    unresolved: z.array(UnresolvedReasonSchema),
+    /** Non-resource observations (duplicates, ambiguities). */
+    findings: z.array(FindingSchema),
+    /**
+     * Classification-signal facts (ADR 0003 D1) for the discovered
+     * resources. Detectors that cannot emit signals contribute an empty
+     * array — conservative defaults classify their resources.
+     */
+    classificationSignals: z.array(ClassificationSignalSchema),
+    /**
+     * Repo-root-relative files the detector actually examined
+     * successfully (coverage evidence, ADR 0003 D4). Optional: a
+     * contribution that omits it leaves the complete-scan attestation
+     * unknown, which fails closed.
+     */
+    scannedPaths: z.array(z.string().min(1)).optional(),
+});
+/**
+ * A normalized graph resource. `id` is the plane-qualified `plane.name`
+ * identity (D5.3); it is `null` while the resource is unclassified and
+ * no plane could be derived. `classification`/`exposure` are `null`
+ * until a classification entry binds the resource. Class-symbol
+ * resources never appear here (consumed by the symbol table).
+ */
+export const GraphResourceSchema = z
+    .strictObject({
+    schemaVersion: SchemaVersionField,
+    /** `plane.name`, or `null` while the plane is unknown (unclassified). */
+    id: z.string().min(1).nullable(),
+    /** Bare resource name (`resourceName` attribute). */
+    name: z.string().min(1),
+    /** Resolved plane, or `null` while unclassified-without-plane. */
+    plane: PlaneSchema.nullable(),
+    /** Detector framework kind, e.g. `sqlalchemy.table`. */
+    kind: z.string().min(1),
+    /** Repo-root-relative source path (posix separators, no `./`). */
+    source: z.string().min(1),
+    /** Exact declaration location in `source`. */
+    location: LocationSchema,
+    /** Classification exposure, or `null` while unclassified. */
+    exposure: ExposureSchema.nullable(),
+    /** Bound classification entry, or `null` while unclassified. */
+    classification: ClassificationSchema.nullable(),
+    /**
+     * Explainability provenance of an automatically classified resource
+     * (ADR 0003 D1): decision fingerprint, contributing signal ids,
+     * rules, defaults, contradictions. Sibling metadata — NEVER
+     * smuggled into detector attributes, never authoritative input.
+     * `null` while the resource is unclassified or the classifier has
+     * not produced a decision for it (manual classifications carry no
+     * trace).
+     */
+    classificationTrace: ClassificationDecisionTraceSchema.nullable(),
+    /** Detector provenance (handshake-pinned id + version). */
+    detector: z.strictObject({ id: z.string().min(1), version: z.string().min(1) }),
+    /** Detector-specific attributes, open payload. */
+    attributes: z.record(z.string(), z.unknown()),
+});
+/** One gate-visible unresolved entry with its detector provenance. */
+export const GraphUnresolvedSchema = z
+    .strictObject({
+    /** Typed reason, verbatim from the detector or graph-synthesized. */
+    reason: UnresolvedReasonSchema,
+    /** Issuing detector; graph-synthesized entries use `gateforge.graph`. */
+    detectorId: z.string().min(1),
+    /** Issuing detector version; `null` for graph-synthesized entries. */
+    detectorVersion: z.string().min(1).nullable(),
+});
+/** Artifact kinds stale-reference validation watches (invariant 9). */
+export const StaleReferenceKindSchema = z.enum(['claim', 'adapter', 'waiver']);
+/**
+ * A reference to a resource that no longer exists. `reference` is the
+ * stale pointer itself: an obligation id, an adapter name, or a
+ * waiver-scoped resource id.
+ */
+export const StaleReferenceSchema = z
+    .strictObject({
+    kind: StaleReferenceKindSchema,
+    /** The stale pointer (key / obligation id / adapter name / resourceId). */
+    reference: z.string().min(1),
+    /** Single-cause human explanation. */
+    detail: z.string().min(1),
+});
+/**
+ * The built resource graph. Deterministic: every array is sorted by a
+ * total order, so identical inputs serialize byte-for-byte identically
+ * under `canonicalJson`.
+ */
+export const ResourceGraphSchema = z
+    .strictObject({
+    schemaVersion: SchemaVersionField,
+    /** Normalized resources, sorted by id (id-less entries last, by name). */
+    resources: z.array(GraphResourceSchema),
+    /** Gate-visible unresolved entries, sorted by location then code. */
+    unresolved: z.array(GraphUnresolvedSchema),
+    /** Detector findings + graph-issued findings, sorted deterministically. */
+    findings: z.array(GraphFindingSchema),
+    /** References to removed/renamed resources (invariant 9), sorted. */
+    stale: z.array(StaleReferenceSchema),
+});
+//# sourceMappingURL=schema.js.map