@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.2

package/dist/spec/infrastructure/sql/compileSql.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The shared front end (ADR-0035 decision 4): SQL text to IR. The parser reads the text and every relation is tagged;
+ * the dialect's `accepts` runs on the raw AST (so a refusal has a source offset); then locations are stripped.
+ * The dialect is D1 unless the caller passes another (`mantle.config.json`'s `dialect`, ADR-0035 decision 5). Nothing in a Worker imports this module.
+ */
+import type { SqlContext, SqlDiagnostic, SqlNode, SqlPlan } from "../../domain/model/SqlIr.js";
+/** A dialect's compile side, as `<dialect>/compile` exports it (ADR-0035 decision 3). */
+export interface SqlDialect {
+    readonly name: string;
+    readonly version: string;
+    /** Throws the first refusal as a `SqlRefusal` with its source offset. */
+    accepts(stmts: SqlNode[], context: SqlContext & {
+        source: string;
+    }, locations: (number | undefined)[]): void;
+}
+/**
+ * The relation names a source reads, less every name it defines as a CTE, or none when it does not parse: the compiler
+ * orders Views by them. ponytail: a CTE named like a View hides that View for the whole source, not only in the CTE's scope.
+ */
+export declare function relationNames(sql: string): Promise<Set<string>>;
+export type CompileSqlResult = {
+    readonly ok: true;
+    readonly plan: SqlPlan;
+} | {
+    readonly ok: false;
+    readonly diagnostic: SqlDiagnostic;
+};
+/** UTF-8 byte offset (what libpg-query reports) to offset, 1-based line and column, and the token there. */
+export declare function locate(source: string, byteOffset: number): Pick<SqlDiagnostic, "offset" | "line" | "column" | "token">;
+/**
+ * Compile one SQL source (a View's `sql`, or a Procedure's statements) to a plan, or say why not.
+ * The first refusal is returned: the compiler stops at the first thing it cannot accept.
+ */
+export declare function compileSql(sql: string, ctx: SqlContext, dialect?: SqlDialect): Promise<CompileSqlResult>;
+//# sourceMappingURL=compileSql.d.ts.map

package/dist/spec/infrastructure/sql/compileSql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compileSql.d.ts","sourceRoot":"","sources":["../../../../src/spec/infrastructure/sql/compileSql.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAO/F,yFAAyF;AACzF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,UAAU,GAAG;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,SAAS,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;CAC9G;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAWrE;AAED,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;CAAE,CAAC;AAE1I,4GAA4G;AAC5G,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC,CAMtH;AAkCD;;;GAGG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAYlH"}

package/dist/spec/infrastructure/sql/compileSql.js

@@ -0,0 +1,92 @@
+import { PG_GRAMMAR } from "../../domain/model/SqlIr.js";
+import { SqlRefusal } from "../../domain/service/SqlRefusal.js";
+import * as d1 from "../../../d1/compile/index.js";
+import { parsePgSql } from "./PgQueryParser.js";
+import { refuseForEveryDialect } from "./frontEnd.js";
+/**
+ * The relation names a source reads, less every name it defines as a CTE, or none when it does not parse: the compiler
+ * orders Views by them. ponytail: a CTE named like a View hides that View for the whole source, not only in the CTE's scope.
+ */
+export async function relationNames(sql) {
+    const names = new Set(), ctes = new Set();
+    const walk = (v) => {
+        if (Array.isArray(v))
+            return v.forEach(walk);
+        if (!v || typeof v !== "object")
+            return;
+        if (typeof v.relname === "string")
+            names.add(v.relname);
+        if (typeof v.ctename === "string")
+            ctes.add(v.ctename);
+        Object.values(v).forEach(walk);
+    };
+    try {
+        walk((await parsePgSql(sql)).stmts);
+    }
+    catch { /* compileSql reports it */ }
+    return new Set([...names].filter((n) => !ctes.has(n)));
+}
+/** UTF-8 byte offset (what libpg-query reports) to offset, 1-based line and column, and the token there. */
+export function locate(source, byteOffset) {
+    const prefix = Buffer.from(source, "utf8").subarray(0, byteOffset).toString("utf8");
+    const lines = prefix.split("\n");
+    const rest = source.slice(prefix.length);
+    const token = /^("[^"]*"|'[^']*'|[\w.$]+|\S)/.exec(rest)?.[0];
+    return { offset: prefix.length, line: lines.length, column: lines[lines.length - 1].length + 1, ...(token ? { token } : {}) };
+}
+function toDiagnostic(e, source) {
+    // a clause the AST gives no position: point at its keyword, never at a quoted string or identifier
+    // that spells it (literals are blanked to the same length, so indexes still match the source)
+    const at = e.keyword?.exec(source.replace(/'(?:[^']|'')*'|"(?:[^"]|"")*"/g, (m) => " ".repeat(m.length)));
+    if (at)
+        return { code: e.code, message: e.message, ...locate(source, Buffer.byteLength(source.slice(0, at.index))), token: at[0] };
+    return { code: e.code, message: e.message, ...(e.offset === undefined ? {} : locate(source, e.offset)) };
+}
+/** Tag every RangeVar a table; the front end retags a CTE in scope `cte` and a View `view`. */
+function tagRelations(v) {
+    if (Array.isArray(v))
+        return v.map(tagRelations);
+    if (!v || typeof v !== "object")
+        return v;
+    const out = {};
+    for (const [k, c] of Object.entries(v))
+        out[k] = tagRelations(c);
+    if ("relname" in out && !("mantle" in out))
+        out.mantle = "table";
+    return out;
+}
+/** Every relation tagged `view` becomes its View's compiled SELECT, as a FROM subquery under the name it was read by. */
+function inlineViews(v, views) {
+    if (Array.isArray(v))
+        return v.map((x) => inlineViews(x, views));
+    if (!v || typeof v !== "object")
+        return v;
+    const rv = v.RangeVar;
+    if (rv?.mantle === "view")
+        return { RangeSubselect: { subquery: { SelectStmt: structuredClone(views[rv.relname].select) }, alias: { aliasname: rv.alias?.aliasname ?? rv.relname } } };
+    return Object.fromEntries(Object.entries(v).map(([k, c]) => [k, inlineViews(c, views)]));
+}
+/** Drop what only diagnostics need. */
+function stripLocations(v) {
+    return JSON.parse(JSON.stringify(v), (k, c) => (k === "location" || k === "rexpr_list_start" || k === "rexpr_list_end" ? undefined : c));
+}
+/**
+ * Compile one SQL source (a View's `sql`, or a Procedure's statements) to a plan, or say why not.
+ * The first refusal is returned: the compiler stops at the first thing it cannot accept.
+ */
+export async function compileSql(sql, ctx, dialect = d1) {
+    try {
+        const parsed = await parsePgSql(sql);
+        const tagged = tagRelations(parsed.stmts);
+        refuseForEveryDialect(tagged, ctx, parsed.locations);
+        const stmts = ctx.views ? inlineViews(tagged, ctx.views) : tagged;
+        dialect.accepts(stmts, { ...ctx, source: sql }, parsed.locations);
+        return { ok: true, plan: { grammar: PG_GRAMMAR, stmts: stripLocations(stmts) } };
+    }
+    catch (e) {
+        if (e instanceof SqlRefusal)
+            return { ok: false, diagnostic: toDiagnostic(e, sql) };
+        throw e;
+    }
+}
+//# sourceMappingURL=compileSql.js.map

package/dist/spec/infrastructure/sql/compileSql.js.map

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

package/dist/spec/infrastructure/sql/frontEnd.d.ts

@@ -0,0 +1,8 @@
+/**
+ * What no dialect may run (ADR-0035 decision 4), refused before the dialect's `accepts` sees the tree. A dialect may refuse
+ * more; it never has to refuse these itself. Runs on the raw AST, so every refusal has a source offset. A relation that
+ * names a CTE in scope is tagged `cte`, so no dialect reads it as a table.
+ */
+import type { SqlContext, SqlNode as N } from "../../domain/model/SqlIr.js";
+export declare function refuseForEveryDialect(stmts: readonly N[], ctx: SqlContext, locations: readonly (number | undefined)[]): void;
+//# sourceMappingURL=frontEnd.d.ts.map

package/dist/spec/infrastructure/sql/frontEnd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontEnd.d.ts","sourceRoot":"","sources":["../../../../src/spec/infrastructure/sql/frontEnd.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,IAAI,CAAC,EAAE,MAAM,6BAA6B,CAAC;AAoB5E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,IAAI,CAO5H"}

package/dist/spec/infrastructure/sql/frontEnd.js

@@ -0,0 +1,100 @@
+import { SqlRefusal } from "../../domain/service/SqlRefusal.js";
+const STATEMENTS = new Set(["SelectStmt", "InsertStmt", "UpdateStmt", "DeleteStmt", "MergeStmt"]);
+const WRITES = new Set(["InsertStmt", "UpdateStmt", "DeleteStmt", "MergeStmt"]);
+/** The functions of decision 2: the only members of the `mantle` and `auth` schemas. */
+const MANTLE_FUNCTIONS = new Set(["mantle.search", "mantle.search_rank", "mantle.near", "mantle.distance", "auth.uid", "auth.role"]);
+/** Functions that change session or server state, reach outside the database, or run SQL text the front end cannot see. */
+const OUTSIDE = /^(pg_(try_)?advisory_|pg_read_(binary_)?file$|pg_ls_|pg_stat_file$|pg_file_|lo_|dblink|pg_(cancel|terminate|signal)_backend$|pg_reload_conf$|pg_rotate_logfile$|pg_notify$|(set|next)val$|(query|table|cursor|schema|database)_to_xml|ts_stat$|ts_rewrite$)/;
+const no = (code, message, at) => {
+    throw new SqlRefusal(code, message, at);
+};
+/** A function's name as PostgreSQL resolves it: a leading catalog (`db.schema.f`) and `pg_catalog.` dropped, case folded. */
+function functionName(n) {
+    const parts = n.funcname.map((x) => String(x.String?.sval).toLowerCase());
+    return parts.slice(-2).join(".").replace(/^pg_catalog\./, "");
+}
+export function refuseForEveryDialect(stmts, ctx, locations) {
+    if (ctx.kind === "view" && (stmts.length !== 1 || !stmts[0].SelectStmt))
+        no("SQL_SHAPE", "a View is exactly one SELECT", locations[1] ?? locations[0]);
+    stmts.forEach((stmt, i) => {
+        const type = Object.keys(stmt)[0];
+        if (!STATEMENTS.has(type))
+            no("SQL_UNSUPPORTED", `statement ${type} is refused`, locations[i]);
+        walk(stmt, new Set(), locations[i], ctx);
+    });
+}
+/** Walk a subtree with the CTE names in scope. PostgreSQL's rule: a CTE sees earlier siblings (every sibling when RECURSIVE). */
+function walk(v, ctes, at, ctx) {
+    if (Array.isArray(v))
+        return v.forEach((x) => walk(x, ctes, at, ctx));
+    if (!v || typeof v !== "object")
+        return;
+    for (const [k, c] of Object.entries(v)) {
+        if (!c || typeof c !== "object" || Array.isArray(c)) {
+            walk(c, ctes, at, ctx);
+            continue;
+        }
+        const n = c;
+        const here = typeof n.location === "number" ? n.location : at;
+        // a write's target is a RangeVar without its type key
+        if (k === "RangeVar" || k === "relation")
+            relation(n, ctes, here, ctx, k === "relation");
+        // a set operation's branches are SELECT bodies without their type key, each with its own WITH
+        else if (STATEMENTS.has(k) || ((k === "larg" || k === "rarg") && "op" in n)) {
+            if (ctx.kind === "view" && WRITES.has(k))
+                no("SQL_SHAPE", "a View reads only: no write in a WITH", here);
+            if (n.intoClause)
+                no("SQL_UNSUPPORTED", "SELECT ... INTO creates a table and is refused", here);
+            const w = n.withClause;
+            const names = (w?.ctes ?? []).map((x) => String(x.CommonTableExpr.ctename));
+            (w?.ctes ?? []).forEach((x, j) => walk(x.CommonTableExpr.ctequery, new Set([...ctes, ...(w.recursive ? names : names.slice(0, j))]), here, ctx));
+            const inner = new Set([...ctes, ...names]);
+            for (const [key, body] of Object.entries(n))
+                if (key !== "withClause")
+                    walk({ [key]: body }, inner, here, ctx);
+            continue;
+        }
+        else if (k === "ColumnRef") {
+            const f = n.fields.map((x) => x.String?.sval);
+            if (f.length === 2 && f[0] === "input" && !Object.hasOwn(ctx.inputs, String(f[1])))
+                no("SQL_COLUMN", `input.${f[1]} is not a declared input`, here);
+        }
+        else if (k === "FuncCall") {
+            const f = functionName(n);
+            if (/^(mantle|auth)\./.test(f) && !MANTLE_FUNCTIONS.has(f))
+                no("SQL_FUNCTION", `${f} is not one of Mantle's functions`, here);
+            if (OUTSIDE.test(f))
+                no("SQL_FUNCTION", `${f} changes session or server state, or reaches outside the database`, here);
+            const setting = n.args?.[0]?.A_Const?.sval?.sval;
+            // a caller setting could be forged from SQL: a name that is not a literal outside mantle.* is refused (setting names ignore case)
+            if ((f === "set_config" || f === "current_setting") && (typeof setting !== "string" || setting.toLowerCase().startsWith("mantle.")))
+                no("SQL_FUNCTION", `${f} of a mantle.* setting is refused`, here);
+        }
+        walk(n, ctes, here, ctx);
+    }
+}
+/**
+ * A relation is a CTE in scope, a declared Schema, or an internal View (ADR-0037 decision 3), by PostgreSQL's name rules
+ * (unquoted names are already folded). A View is tagged `view`; the compiler inlines it before any dialect sees the tree.
+ */
+function relation(n, ctes, at, ctx, written) {
+    const name = String(n.relname);
+    if (n.schemaname || n.catalogname)
+        no("SQL_RELATION", `${n.schemaname ?? n.catalogname}.${name}: a relation is a declared Schema, never schema-qualified`, at);
+    if (ctes.has(name)) {
+        n.mantle = "cte";
+        return;
+    }
+    const view = Object.hasOwn(ctx.schemas, name) ? undefined : ctx.views?.[name];
+    if (view) {
+        if (written)
+            no("SQL_WRITE", `${name} is a View: a View is read, never written`, at);
+        if (view.refusal)
+            no("SQL_RELATION", view.refusal, at);
+        n.mantle = "view";
+        return;
+    }
+    if (!Object.hasOwn(ctx.schemas, name))
+        no("SQL_RELATION", `${name} is not a declared Schema`, at);
+}
+//# sourceMappingURL=frontEnd.js.map

package/dist/spec/infrastructure/sql/frontEnd.js.map

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

package/dist/spec/infrastructure/sql/index.d.ts

@@ -0,0 +1,4 @@
+/** `sql/` — the CLI-side Store SQL compiler (ADR-0034). The runtime never imports this folder. */
+export * from "./compileSql.js";
+export * from "./compilePlan.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/spec/infrastructure/sql/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/spec/infrastructure/sql/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}

package/dist/spec/infrastructure/sql/index.js

@@ -0,0 +1,4 @@
+/** `sql/` — the CLI-side Store SQL compiler (ADR-0034). The runtime never imports this folder. */
+export * from "./compileSql.js";
+export * from "./compilePlan.js";
+//# sourceMappingURL=index.js.map

package/dist/spec/infrastructure/sql/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/spec/infrastructure/sql/index.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}

package/dist/spec/kernel/diagnostic.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Structured diagnostic shape — see ADR-0008. Used uniformly across
+ * static validation, boot-time, and runtime feedback. The public `test`
+ * phase remains reserved for consumer-authored test diagnostics; Core's
+ * shipped performance harnesses emit purpose-shaped reports instead.
+ *
+ * Codes are unprefixed UPPER_SNAKE strings; the `phase` field
+ * disambiguates which loop emitted each diagnostic. The same `code`
+ * may appear in multiple phases when it names the same root cause —
+ * AI consumers can group by code OR filter by phase.
+ *
+ * `candidates` is security-sensitive at runtime; `redactForWire`
+ * strips it before HTTP egress.
+ */
+export type Phase = "validate" | "test" | "boot" | "runtime";
+/**
+ * Closed catalog of diagnostic codes the SDK emits across all phases.
+ * Per ADR-0008, spec **defines** the catalog; runtime / cli / adapters
+ * **emit** them. Codes in the cross-phase and runtime-only sections
+ * below are not raised by spec source — they live here because the
+ * catalog is the public contract, not the union of what spec happens
+ * to throw today. Adding a new code is a grammar-revise event
+ * (ADR-0001).
+ *
+ * Single source of truth: the const array drives `DiagnosticCode`
+ * (type), so adding a code is one edit.
+ */
+export declare const DIAGNOSTIC_CODES: readonly ["RESOURCE_EXHAUSTED", "RESOURCE_UNAVAILABLE", "RATE_LIMITED", "OUTCOME_UNKNOWN", "PARTIAL_FAILURE", "PRECONDITION_FAILED", "INVALID_MANIFEST_ENVELOPE", "DUPLICATE_NAME", "VIEW_INPUT_INVALID_SHAPE", "VIEW_INPUT_RESERVED_NAME", "VIEW_CACHE_INVALID", "VIEW_UI_INVALID", "REQUIRED_FIELD_UNKNOWN", "INVALID_PATTERN", "JSON_SCHEMA_UNSUPPORTED", "JSON_SCHEMA_REF_INVALID", "JSON_SCHEMA_LIMIT_EXCEEDED", "AUTH_PREDICATE_NOT_IN_ENUM", "GUARD_PROCEDURE_UNKNOWN", "GUARD_SELF_REFERENCE", "GUARD_PROCEDURE_NOT_REF", "GUARD_CHAIN_NOT_ALLOWED", "SCHEMA_INDEX_INVALID", "SCHEMA_INDEX_FIELD_UNKNOWN", "UNIQUE_INDEX_FIELD_UNKNOWN", "SCHEMA_SEARCH_INVALID", "SCHEMA_SEARCH_FIELD_UNKNOWN", "SCHEMA_TTL_INVALID", "SCHEMA_UI_INVALID", "SCHEMA_NAME_CASE_COLLISION", "FIELD_NAME_CASE_COLLISION", "MANIFEST_ROOT_NOT_FOUND", "MANIFEST_READ_FAILED", "GENERATE_FEATURE_DEPENDENCY_MISSING", "SQL_SYNTAX", "SQL_UNSUPPORTED", "SQL_FUNCTION", "SQL_RELATION", "SQL_COLUMN", "SQL_WRITE", "SQL_SHAPE", "SQL_TYPE", "FIXTURE_SCHEMA_VIOLATION", "HANDLER_NOT_REGISTERED", "HANDLER_NOT_DECLARED", "PLAN_FINGERPRINT_MISMATCH", "SCHEDULE_NOT_WIRED", "STORAGE_CHANGE_BLOCKED", "STORAGE_TABLE_NOT_OWNED", "INVOCATION_DEPTH_EXCEEDED", "TRIGGER_TARGET_PROCEDURE_UNKNOWN", "SCHEDULE_INPUT_INVALID", "SCHEDULE_AUTH_INVALID", "TRIGGER_PATH_COLLISION", "TRIGGER_PATH_INVALID", "MCP_TOOL_NAME_COLLISION", "MCP_TOOL_DESCRIPTION_MISSING", "MCP_TOOL_INPUT_UNION_AMBIGUOUS", "MCP_TOOL_INPUT_UNBOUNDED", "MANTLE_REF_INVALID", "PROCEDURE_TARGET_INVALID", "PROCEDURE_NOT_FOUND", "NOT_FOUND", "METHOD_NOT_ALLOWED", "LIFECYCLE_SCHEMA_UNKNOWN", "LIFECYCLE_HOOK_REJECTED", "LIFECYCLE_TARGET_NOT_REF", "SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES", "TRANSLATES_PARENT_UNKNOWN", "TRANSLATES_REQUIRES_LOCALIZED", "TRANSLATES_REQUIRES_CONTENT_FIELD", "TRANSLATES_FIELD_NOT_IN_PARENT", "TRANSLATES_FIELD_NOT_IN_CHILD", "TRANSLATES_PARENT_IS_LOCALIZED", "SCHEMA_TTL_TRANSLATION_UNSUPPORTED", "INPUT_VALIDATION_FAILED", "UNAUTHENTICATED", "AUTH_DENIED", "ENTITLEMENT_REQUIRED", "CONFLICT", "DISPATCHER_NOT_BUILT", "INTERNAL_ERROR", "OUTPUT_VALIDATION_FAILED", "INVALID_LOCALE", "MEDIA_NOT_CONFIGURED", "SITE_NOT_CONFIGURED", "MEDIA_UPLOAD_EXPIRED", "MEDIA_OBJECT_NOT_FOUND", "MEDIA_MIME_REJECTED", "MEDIA_SIZE_EXCEEDED", "MEDIA_SVG_REJECTED", "MEDIA_CHECKSUM_MISMATCH", "MEDIA_PURPOSE_REJECTED", "MEDIA_VARIANTS_INCOMPLETE", "MEDIA_VARIANT_SIZE_EXCEEDED", "MEDIA_VARIANTS_SUSPICIOUS_SIZE", "MEDIA_ASSET_NOT_FOUND"];
+export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+export interface SourcePosition {
+    readonly line: number;
+    readonly column: number;
+    readonly offset: number;
+}
+export interface SourceSpan {
+    readonly start: SourcePosition;
+    readonly end: SourcePosition;
+}
+/** Authored location retained independently from a rendered diagnostic path. */
+export interface SourceLocation {
+    readonly sourceId: string;
+    readonly documentIndex: number;
+    /** JSON Pointer inside the YAML document. */
+    readonly path: string;
+    readonly span?: SourceSpan;
+}
+export interface Diagnostic {
+    readonly code: DiagnosticCode;
+    readonly phase: Phase;
+    readonly severity: "error" | "warning";
+    readonly path: string;
+    readonly source?: SourceLocation;
+    readonly value?: unknown;
+    readonly expected?: string;
+    readonly candidates?: readonly string[];
+    readonly suggestion?: string;
+    readonly message: string;
+    /** Safe effect/retry facts supplied by a port; never provider payloads. */
+    readonly failure?: {
+        readonly outcome: "not-applied" | "partial" | "unknown";
+        readonly retry: "never" | "after-change" | "safe" | "reconcile";
+        readonly resource?: string;
+    };
+    /** Why a `CONFLICT` write failed (ADR-0032 decision 1); `opIndex` names the statement in the batch (ADR-0034). */
+    readonly conflict?: {
+        readonly opIndex?: number;
+        readonly reason: "lock" | "expect" | "unique";
+    };
+}
+/**
+ * HTTP status mapping for codes that surface on the wire (runtime
+ * phase). Codes not in this map default to 500 when surfaced over
+ * HTTP. Validate / test / boot phases don't map to HTTP — they
+ * surface in CLI exit codes / thrown errors / Worker init logs.
+ *
+ * Narrowed to a status-literal union so adding a code with a status
+ * outside the v0.1 set fails compile.
+ */
+export type RuntimeHttpStatus = 400 | 401 | 402 | 403 | 404 | 405 | 409 | 410 | 412 | 429 | 500 | 501 | 503 | 507;
+export declare const HTTP_STATUS_BY_CODE: Readonly<Partial<Record<DiagnosticCode, RuntimeHttpStatus>>>;
+/** Resolve a Diagnostic's HTTP status for wire egress; unknown codes
+ *  default to 500. Lives in the kernel so every adapter shares one
+ *  mapping. */
+export declare function httpStatusFor(d: Diagnostic): RuntimeHttpStatus;
+/**
+ * Build a Diagnostic with a derived default `message`. Call sites may supply
+ * contextual prose, but the structured fields remain authoritative.
+ */
+export declare function makeDiagnostic(input: Omit<Diagnostic, "message"> & {
+    message?: string;
+}): Diagnostic;
+/** Phase-stamping helpers — equivalent to `makeDiagnostic({...input, phase})`
+ *  but read cleaner at call sites. `phase: "test"` has no Core helper because
+ *  the shipped performance harnesses emit purpose-shaped reports; the phase
+ *  remains part of the public Diagnostic contract for consumer tests. */
+export declare const validateDiagnostic: (input: PhaselessInput) => Diagnostic;
+export declare const bootDiagnostic: (input: PhaselessInput) => Diagnostic;
+export declare const runtimeDiagnostic: (input: PhaselessInput) => Diagnostic;
+type PhaselessInput = Omit<Diagnostic, "phase" | "message"> & {
+    message?: string;
+};
+declare const BRAND: unique symbol;
+/**
+ * Throwable carrier for one or more Diagnostics. Layers that surface
+ * an error across a transport boundary (HTTP handler, MCP tool call,
+ * render pipeline) throw this so the boundary catch can detect a
+ * structured payload and emit it on the wire instead of falling back
+ * to the INTERNAL_ERROR envelope reserved for genuinely unexpected
+ * throws.
+ */
+export declare class DiagnosticError extends Error {
+    /**
+     * A handler bundled with its own copy of this class (a closed-module artifact) still throws a DiagnosticError: `instanceof`
+     * matches the brand, not the class identity, so the runtime keeps its code instead of reporting INTERNAL_ERROR.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
+    readonly [BRAND] = true;
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(diagnostic: Diagnostic | readonly Diagnostic[], options?: ErrorOptions);
+    /** First diagnostic — convenience for single-diagnostic call sites. */
+    get diagnostic(): Diagnostic;
+}
+/**
+ * Strip security-sensitive fields for wire egress. Per ADR-0008:
+ * never expose `candidates` to untrusted callers — that leaks
+ * schema information. Internal phases (validate / test / boot)
+ * skip this redaction.
+ */
+export declare function redactForWire(d: Diagnostic): Diagnostic;
+/**
+ * Walk a JSON Pointer (RFC 6901) on a value. Returns `undefined` for
+ * any miss. Best-effort — used to surface the offending value inside
+ * a diagnostic, not for strict pointer dereferencing.
+ */
+export declare function readJsonPointer(root: unknown, jsonPointer: string): unknown;
+export {};
+//# sourceMappingURL=diagnostic.d.ts.map

package/dist/spec/kernel/diagnostic.d.ts.map

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