@typed-sql/core 2.0.0-rc.1 → 2.1.0-rc.1

package/CHANGELOG.md

@@ -1,5 +1,175 @@
 # @typed-sql/core
 
+## 2.1.0-rc.1
+
+### Patch Changes
+
+- Publish the coherent 2.1.0-rc.1 release-candidate train.
+
+## 2.1.0-rc.0
+
+### Minor Changes
+
+- 58bd4d1: Add the versioned, serializable source-analysis service shared by batch checks and editor tooling.
+  Results carry deterministic source, project, schema, type-policy, grammar, and capability identities;
+  cancellation and source, query-count, structural-variant, and generated-declaration limits fail closed.
+- 58aa9ef: Add a grammar-neutral serialized artifact compatibility identity and deterministic compatibility outcomes, and use the shared identity contract for query-manifest cache reuse.
+- 65b662f: Add structured opt-in debug events and confirmed support-bundle generation with privacy-safe default redaction.
+- e433feb: Allow non-empty arrays of typed SQL fragments to be interpolated directly as homogeneous,
+  comma-separated structure. Add fail-closed compiler analysis for direct map callbacks and fragment
+  literals, cardinality-independent artifacts, bounded prepared-cardinality caches, shared grammar
+  conformance, and runtime limits while preserving ordinary arrays as single bound values.
+- 0efc90c: Add neutral column charset and collation evidence, generated versioned MySQL built-in catalogs,
+  catalog-backed type and function availability, MySQL collation coercibility, and signed/unsigned
+  numeric expression resolution.
+  Conformance v2 now compares grammar analysis against the neutral resolved-column contract while
+  allowing grammar-owned result evidence.
+- 6f5b977: Resolve PostgreSQL operators and snapshot v2 routines through a grammar-owned candidate selector
+  that uses canonical types, cast contexts, preferred categories, unknown-literal rules, domains,
+  arrays, ranges, enums, and the `anyelement` and `anycompatible` polymorphic families.
+  Named, defaulted, expanded-variadic, and explicit-variadic routine calls now select against snapshot
+  argument evidence, while known invalid explicit casts produce a stable diagnostic.
+  The versioned core catalog now recognizes PostgreSQL temporal, bit-string, network, geometric,
+  full-text, XML, range, multirange, object-identifier, and related scalar types. Unary numeric and
+  bitwise operators, plus binary integer and bit-string operators, now resolve through typed
+  candidates and reject invalid operands. Date, timestamp, time, and interval arithmetic now uses
+  asymmetric PostgreSQL signatures, with parameter inference deferred until candidate selection.
+  Built-in range/multirange containment and arithmetic, network containment and address arithmetic,
+  full-text search composition, JSON-path predicates and deletion, and their multi-character tokens
+  now use exact grammar-owned signatures.
+  Geometric transformation, position, intersection, distance, containment, and relationship operators
+  now resolve through their exact operand and result signatures, including prefix forms.
+  Numeric promotion, mathematical prefix, bit-string shift, binary/JSON/text concatenation, money,
+  `pg_lsn`, and tuple-identifier operators now use catalog-derived signatures and coercions.
+  Array subscripts infer nullable element types, slices preserve the array type, omitted bounds are
+  represented explicitly, index parameters infer `integer`, and nested array mappings retain every dimension.
+  `ANY`, `SOME`, and `ALL` comparisons now resolve array elements or single-column subqueries through
+  the operator catalog, while row comparisons validate arity and select an operator for each field pair.
+  Parenthesized composite field selection now uses snapshot v2 field evidence for its database type,
+  TypeScript type, nullability, parameter context, and unknown-field diagnostics.
+  `COLLATE` now preserves collatable expression types, and `AT TIME ZONE` resolves PostgreSQL's exact
+  timestamp, timestamp-with-time-zone, and time-with-time-zone conversions with text or interval zones.
+  PostgreSQL 17 and newer also resolve and version-gate the corresponding `AT LOCAL` forms.
+  Scalar and row-valued `IN` lists and subqueries now validate equality candidates, numeric literals,
+  row arity, composite field comparability, nullability, and per-position parameter contexts.
+  The versioned cast catalogs now include every direct `pg_cast` conversion among shipped core types
+  for PostgreSQL 14 through 18, including the PostgreSQL 15 geometric removal and PostgreSQL 18
+  integer/bytea additions. Automatic assignment-to-string and explicit string I/O casts follow the
+  server's fallback conversion rules.
+  PostgreSQL interval literals now parse prefix precision, every valid field and field-range qualifier,
+  suffix second precision, and qualified interval cast types while retaining typed-literal source spans.
+  All forms resolve through the canonical `interval` type, and invalid field ranges fail during parsing.
+  JSON, JSONB, and JSONPATH typed literals now preserve their grammar-owned cast form. The core catalog
+  and resolver cover `jsonb_path_exists`, `jsonb_path_match`, query-array, query-first, and set-returning
+  query variants, including timezone-aware forms, optional variables/silent arguments, and nullability.
+  Database parameter identities are now retained even when their configured TypeScript mapping is
+  `unknown`, so JSON and other deliberately opaque codecs still produce typed prepared parameters.
+  PostgreSQL 17 and newer now parse and resolve the grammar-owned `JSON_EXISTS` SQL/JSON expression,
+  including formatted inputs, `PASSING` variables, error behavior, parameter identities, nullability,
+  and server-version diagnostics.
+  The grammar-owned PostgreSQL 17 `JSON_QUERY` form also resolves returning types, JSON output formats,
+  wrapper and quote behavior, constant `ON EMPTY` and `ON ERROR` defaults, and exact output nullability.
+  PostgreSQL 17 `JSON_VALUE` now resolves scalar return types and behaviors while preserving its
+  always-possible SQL null result for JSON null and rejecting unsupported collection or format clauses.
+  PostgreSQL 16 and newer now parse and resolve the standard `JSON_OBJECT` and `JSON_ARRAY`
+  constructors, including key/value and query forms, null handling, unique-key declarations, formatted
+  inputs, encoded returns, parameter identities, non-null output types, and server-version diagnostics.
+  Legacy and quoted `json_object(...)` calls remain ordinary catalog-backed routine calls.
+  PostgreSQL 17 and newer also own `JSON`, `JSON_SCALAR`, and `JSON_SERIALIZE`, including JSON-compatible
+  inputs, uniqueness declarations, scalar and composite conversion, string or binary returns, UTF-8
+  encoding, parameter inference, null propagation, and version diagnostics. The overlapping pre-17
+  functional `json(...)` cast keeps its earlier cast semantics.
+  PostgreSQL 16 and newer now own `IS JSON` and `IS NOT JSON` predicates across value, scalar,
+  array, object, and unique-key constraints, with JSON-compatible input validation, text parameter
+  inference, SQL-null propagation, and server-version diagnostics.
+  PostgreSQL 16 and newer now also own the standard `JSON_OBJECTAGG` and `JSON_ARRAYAGG` grammar,
+  including null and uniqueness clauses, aggregate-local ordering, `FILTER`, `OVER`, formatted inputs,
+  encoded returns, grouping validation, parameter inference, nullable empty-input results, and
+  server-version diagnostics.
+  PostgreSQL 17 `JSON_TABLE` now owns its table-reference grammar and resolves root, ordinality,
+  scalar, formatted, `EXISTS`, and nested columns with implicit lateral scope, alias lists, declared
+  types, behavior validation, nested null-padding, and server-version diagnostics.
+
+  Expose optional routine argument names and default evidence through the neutral resolver bridge so
+  grammar packages can implement named, defaulted, and variadic call selection.
+- 1c64475: Complete PostgreSQL DML parsing and analysis for identity overriding, `ON CONFLICT` targets and the
+  `excluded` namespace, row assignments, source-aware update/delete returning, versioned `MERGE`, and
+  PostgreSQL 18 old/new `RETURNING` aliases. Version-dependent forms now use server-major evidence and
+  fail closed when that evidence is absent or outside the feature's supported range. Snapshot v2 index
+  evidence now verifies expression, operator-class, collation, and partial-predicate conflict targets,
+  while insert/select, update, and merge writes propagate parameter types and reject known-incompatible
+  source types.
+
+  The neutral resolver snapshot bridge now exposes optional index and constraint-deferrability evidence
+  so grammar packages can consume schema v2 conflict-target metadata without importing schema internals.
+- 1c64475: Add canonical schema snapshot format 2 with isolated v1/v2 codecs, conservative v1 upgrades,
+  neutral relation/constraint/index/type/routine evidence, and complete provider introspection.
+  Resolvers now consume structural write and routine evidence, while drift, compatibility, manifests,
+  verification proofs, and plan artifacts bind to the schema format and canonical hash.
+- 1c64475: Add deterministic versioned dialect capability states backed by normalized server versions,
+  settings, extensions, and compile options. Query manifests now invalidate on capability changes and
+  record evidence for capabilities each query uses, while the CLI exposes a human-readable capability
+  report. The boolean capability map remains available as an additive migration bridge.
+
+### Patch Changes
+
+- ff0e3bb: Harden PostgreSQL execution with policy-owned scalar and array codecs, runtime extension codec OID
+  resolution, generated-snapshot compatibility checks, bounded per-connection prepared-statement
+  caches with schema and search-path invalidation, and structured driver failure classifications.
+  Keep the shared `TSQ230` diagnostic registry text grammar-neutral.
+- 1c64475: Resolve SQLite core built-ins, operators, coercions, arities, nullability, and in-band function
+  release boundaries from SQLite-owned catalog data. Add a stable diagnostic for invalid SQLite
+  built-in invocations and fail closed when version-gated functions lack usable server evidence.
+
+## 2.0.0
+
+### Major Changes
+
+- 29afc3d: Add conservative semantic primary/replica routing over application-owned databases, scoped
+  read-after-write pinning, explicit role requirements, stable unsafe-route errors, dialect runtime
+  semantic resolvers, and bounded abortable transaction retry policies with native PostgreSQL and
+  MySQL error classifiers. Parse and classify dialect locking reads so uncertain or affine work
+  always fails closed to primary.
+- 3f063f6: Add deterministic, secret-free query manifests with bounded structural variants, inferred result
+  and parameter descriptions, semantic evidence, runtime-correlatable fingerprints, unresolved
+  entries, compatible parsing, canonical serialization, incremental per-file reuse, tsconfig project
+  discovery, and a dedicated CLI command.
+- 6a7ae58: Add opt-in live query verification through grammar-owned PostgreSQL PREPARE and MySQL
+  COM_STMT_PREPARE adapters, bounded neutral comparison, deterministic secret-free proof artifacts,
+  offline cache validation, explicit unsupported classifications, CLI workflows, real database E2E,
+  and performance budgets.
+- b06fd0a: Add grammar-neutral optional adapter capability discovery, typed PostgreSQL COPY import and export
+  through application-owned `pg-copy-streams`, and typed MySQL LOAD DATA import through mysql2's
+  application-owned infile stream. Bulk transfers preserve ordinary `INSERT` parameter evidence,
+  enforce structural row stability, apply bounded backpressure, support cancellation and progress,
+  and integrate with transaction ownership and conservative connection cleanup.
+- 3050209: Add the dialect contract v4 semantic query evidence foundation. PostgreSQL and MySQL now report operation, dependencies, cardinality, volatility, locking, connection affinity, and required capabilities; compiler results add deterministic query and structural-variant fingerprints and conservatively merged source-mapped semantics. Schema snapshots can record function volatility, and the AST package exposes a neutral statement walker for grammar implementations.
+- 1b054b6: Add an adapter-neutral, redacted database observation lifecycle for queries, cardinality contracts,
+  batches, PostgreSQL pipelines, streams, cancellation, and nested transactions. Runtime fingerprints
+  correlate with compiler structural variants while SQL, parameter values, connection configuration,
+  and driver causes remain excluded by default. Publish the optional OpenTelemetry bridge with current
+  database semantic conventions and explicit high-cardinality or exception-capture opt-ins.
+- b4f1b6e: Add deterministic migration compatibility analysis across before/after schema snapshots and query
+  manifests. Reports classify both rolling-deployment directions, retain exact source and dependency
+  evidence, fail closed for unknown semantics, redact defaults and paths, and support configurable CI
+  severity through `typed-sql compat`.
+- 87189c3: Add grammar-neutral `all`, `one`, and `maybeOne` execution with exact row types, stable cardinality
+  and cancellation errors, explicit adapter capabilities, AbortSignal support, and absolute deadlines.
+  The pg and mysql2 adapters conservatively discard interrupted connections, including transaction
+  leases, while the existing uncontrolled `execute` path remains unchanged.
+- e654fae: Add opt-in Standard Schema V1 result validation with compile-time output compatibility, immutable
+  query attachment, sync and async validators, redacted fingerprinted errors, and consistent decoded-row
+  handling across buffered cardinality methods, batches, PostgreSQL pipelines, streams, and transactions.
+- b2ec119: Add opt-in, grammar-neutral query-plan governance with PostgreSQL and MySQL structured EXPLAIN
+  adapters, transient application-owned samples, redacted fingerprint-keyed artifacts, absolute and
+  comparable regression budgets, explicit uncertainty, CLI capture and review, documentation, and
+  performance coverage.
+
+### Patch Changes
+
+- 7ea5d2f: Match the Standard Schema V1 optional-property contract under `exactOptionalPropertyTypes` so
+  unwrapped Zod, Valibot, and other conforming validators are accepted directly.
+
 ## 2.0.0-rc.1
 
 ### Patch Changes

package/dist/packages/core/src/artifact-compatibility.d.ts

@@ -0,0 +1,46 @@
+export declare const ARTIFACT_COMPATIBILITY_IDENTITY_FORMAT_VERSION: 1;
+export declare const CORE_ARTIFACT_COMPATIBILITY_VERSION: "typed-sql-core-v1";
+export type ArtifactCompatibilityOutcome = "compatible" | "requires-reanalysis" | "requires-reintrospection" | "unsupported-target" | "corrupt-artifact";
+export interface ArtifactCompatibilityIdentity {
+    readonly formatVersion: typeof ARTIFACT_COMPATIBILITY_IDENTITY_FORMAT_VERSION;
+    readonly artifact: {
+        readonly kind: string;
+        readonly version: string;
+        readonly algorithm?: string;
+    };
+    readonly producer: {
+        readonly core: string;
+        readonly compiler?: string;
+    };
+    readonly grammar: {
+        readonly id: string;
+        readonly version: string;
+        readonly catalogRevision?: string;
+        readonly capabilityFingerprint: string;
+    };
+    readonly server?: {
+        readonly product: string;
+        readonly version: string;
+        readonly capabilityFingerprint: string;
+    };
+    readonly schema: {
+        readonly formatVersion: 1 | 2;
+        readonly hash: string;
+    };
+    readonly typePolicyHash: string;
+    readonly runtimeSettingsHash?: string;
+    readonly source?: {
+        readonly hash: string;
+        readonly query?: string;
+    };
+    readonly extensions?: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactCompatibilityAssessment {
+    readonly outcome: ArtifactCompatibilityOutcome;
+    readonly reasons: readonly string[];
+    readonly candidate?: ArtifactCompatibilityIdentity;
+}
+export declare function parseArtifactCompatibilityIdentity(value: unknown): ArtifactCompatibilityIdentity;
+export declare function serializeArtifactCompatibilityIdentity(identity: ArtifactCompatibilityIdentity): string;
+export declare function assessArtifactCompatibility(referenceValue: ArtifactCompatibilityIdentity, candidateValue: unknown): ArtifactCompatibilityAssessment;
+//# sourceMappingURL=artifact-compatibility.d.ts.map

package/dist/packages/core/src/artifact-compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifact-compatibility.d.ts","sourceRoot":"","sources":["../../../../src/artifact-compatibility.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,8CAA8C,EAAG,CAAU,CAAC;AACzE,eAAO,MAAM,mCAAmC,EAAG,mBAA4B,CAAC;AAEhF,MAAM,MAAM,4BAA4B,GACpC,YAAY,GACZ,qBAAqB,GACrB,0BAA0B,GAC1B,oBAAoB,GACpB,kBAAkB,CAAC;AAEvB,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,aAAa,EAAE,OAAO,8CAA8C,CAAC;IAC9E,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;KACxC,CAAC;IACF,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;KACxC,CAAC;IACF,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,aAAa,EAAE,CAAC,GAAG,CAAC,CAAC;QAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,OAAO,EAAE,4BAA4B,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,6BAA6B,CAAC;CACpD;AAoCD,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,OAAO,GAAG,6BAA6B,CA0FhG;AAED,wBAAgB,sCAAsC,CAAC,QAAQ,EAAE,6BAA6B,GAAG,MAAM,CAEtG;AAED,wBAAgB,2BAA2B,CACzC,cAAc,EAAE,6BAA6B,EAC7C,cAAc,EAAE,OAAO,GACtB,+BAA+B,CAwDjC"}

package/dist/packages/core/src/artifact-compatibility.js

@@ -0,0 +1,168 @@
+export const ARTIFACT_COMPATIBILITY_IDENTITY_FORMAT_VERSION = 1;
+export const CORE_ARTIFACT_COMPATIBILITY_VERSION = "typed-sql-core-v1";
+const record = (value) => typeof value === "object" && value !== null;
+function keys(value, allowed, path) {
+    const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+    if (unknown.length > 0)
+        throw new TypeError(`${path} contains unknown fields: ${unknown.sort().join(", ")}`);
+}
+function text(value, path) {
+    if (typeof value !== "string" || value.length === 0 || value.includes("\0")) {
+        throw new TypeError(`${path} must be a non-empty string without null bytes`);
+    }
+    return value;
+}
+function object(value, path) {
+    if (!record(value) || Array.isArray(value))
+        throw new TypeError(`${path} must be an object`);
+    return value;
+}
+function jsonValue(value, path) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new TypeError(`${path} must contain finite JSON numbers`);
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map((item, index) => jsonValue(item, `${path}[${index}]`));
+    const source = object(value, path);
+    return Object.fromEntries(Object.keys(source)
+        .sort()
+        .map((key) => [key, jsonValue(source[key], `${path}.${key}`)]));
+}
+export function parseArtifactCompatibilityIdentity(value) {
+    const root = object(value, "artifact compatibility identity");
+    keys(root, [
+        "formatVersion",
+        "artifact",
+        "producer",
+        "grammar",
+        "server",
+        "schema",
+        "typePolicyHash",
+        "runtimeSettingsHash",
+        "source",
+        "extensions",
+    ], "artifact compatibility identity");
+    if (root.formatVersion !== ARTIFACT_COMPATIBILITY_IDENTITY_FORMAT_VERSION) {
+        throw new TypeError(`Unsupported artifact compatibility identity format ${String(root.formatVersion)}`);
+    }
+    const artifact = object(root.artifact, "identity.artifact");
+    keys(artifact, ["kind", "version", "algorithm"], "identity.artifact");
+    const producer = object(root.producer, "identity.producer");
+    keys(producer, ["core", "compiler"], "identity.producer");
+    const grammar = object(root.grammar, "identity.grammar");
+    keys(grammar, ["id", "version", "catalogRevision", "capabilityFingerprint"], "identity.grammar");
+    const schema = object(root.schema, "identity.schema");
+    keys(schema, ["formatVersion", "hash"], "identity.schema");
+    if (schema.formatVersion !== 1 && schema.formatVersion !== 2) {
+        throw new TypeError("identity.schema.formatVersion must be 1 or 2");
+    }
+    const server = root.server === undefined ? undefined : object(root.server, "identity.server");
+    if (server !== undefined)
+        keys(server, ["product", "version", "capabilityFingerprint"], "identity.server");
+    const source = root.source === undefined ? undefined : object(root.source, "identity.source");
+    if (source !== undefined)
+        keys(source, ["hash", "query"], "identity.source");
+    const extensions = root.extensions === undefined
+        ? undefined
+        : jsonValue(object(root.extensions, "identity.extensions"), "identity.extensions");
+    return Object.freeze({
+        formatVersion: ARTIFACT_COMPATIBILITY_IDENTITY_FORMAT_VERSION,
+        artifact: Object.freeze({
+            kind: text(artifact.kind, "identity.artifact.kind"),
+            version: text(artifact.version, "identity.artifact.version"),
+            ...(artifact.algorithm === undefined
+                ? {}
+                : { algorithm: text(artifact.algorithm, "identity.artifact.algorithm") }),
+        }),
+        producer: Object.freeze({
+            core: text(producer.core, "identity.producer.core"),
+            ...(producer.compiler === undefined ? {} : { compiler: text(producer.compiler, "identity.producer.compiler") }),
+        }),
+        grammar: Object.freeze({
+            id: text(grammar.id, "identity.grammar.id"),
+            version: text(grammar.version, "identity.grammar.version"),
+            ...(grammar.catalogRevision === undefined
+                ? {}
+                : { catalogRevision: text(grammar.catalogRevision, "identity.grammar.catalogRevision") }),
+            capabilityFingerprint: text(grammar.capabilityFingerprint, "identity.grammar.capabilityFingerprint"),
+        }),
+        ...(server === undefined
+            ? {}
+            : {
+                server: Object.freeze({
+                    product: text(server.product, "identity.server.product"),
+                    version: text(server.version, "identity.server.version"),
+                    capabilityFingerprint: text(server.capabilityFingerprint, "identity.server.capabilityFingerprint"),
+                }),
+            }),
+        schema: Object.freeze({
+            formatVersion: schema.formatVersion,
+            hash: text(schema.hash, "identity.schema.hash"),
+        }),
+        typePolicyHash: text(root.typePolicyHash, "identity.typePolicyHash"),
+        ...(root.runtimeSettingsHash === undefined
+            ? {}
+            : { runtimeSettingsHash: text(root.runtimeSettingsHash, "identity.runtimeSettingsHash") }),
+        ...(source === undefined
+            ? {}
+            : {
+                source: Object.freeze({
+                    hash: text(source.hash, "identity.source.hash"),
+                    ...(source.query === undefined ? {} : { query: text(source.query, "identity.source.query") }),
+                }),
+            }),
+        ...(extensions === undefined ? {} : { extensions: Object.freeze(extensions) }),
+    });
+}
+export function serializeArtifactCompatibilityIdentity(identity) {
+    return `${JSON.stringify(parseArtifactCompatibilityIdentity(identity), null, 2)}\n`;
+}
+export function assessArtifactCompatibility(referenceValue, candidateValue) {
+    const reference = parseArtifactCompatibilityIdentity(referenceValue);
+    let candidate;
+    try {
+        candidate = parseArtifactCompatibilityIdentity(candidateValue);
+    }
+    catch {
+        return Object.freeze({ outcome: "corrupt-artifact", reasons: Object.freeze(["identity-invalid"]) });
+    }
+    const unsupported = [];
+    const reintrospection = [];
+    const reanalysis = [];
+    const compare = (left, right, reason, target) => {
+        if (left !== undefined && left !== right)
+            target.push(reason);
+    };
+    compare(reference.artifact.kind, candidate.artifact.kind, "artifact-kind-changed", unsupported);
+    compare(reference.artifact.version, candidate.artifact.version, "artifact-version-changed", unsupported);
+    compare(reference.artifact.algorithm, candidate.artifact.algorithm, "artifact-algorithm-changed", unsupported);
+    compare(reference.producer.core, candidate.producer.core, "core-compatibility-changed", unsupported);
+    compare(reference.producer.compiler, candidate.producer.compiler, "compiler-compatibility-changed", reanalysis);
+    compare(reference.grammar.id, candidate.grammar.id, "grammar-changed", unsupported);
+    compare(reference.grammar.version, candidate.grammar.version, "grammar-version-changed", reintrospection);
+    compare(reference.grammar.catalogRevision, candidate.grammar.catalogRevision, "catalog-revision-changed", reintrospection);
+    compare(reference.grammar.capabilityFingerprint, candidate.grammar.capabilityFingerprint, "grammar-capabilities-changed", reintrospection);
+    compare(reference.server?.product, candidate.server?.product, "server-product-changed", reintrospection);
+    compare(reference.server?.version, candidate.server?.version, "server-version-changed", reintrospection);
+    compare(reference.server?.capabilityFingerprint, candidate.server?.capabilityFingerprint, "server-capabilities-changed", reintrospection);
+    if (reference.schema.formatVersion !== candidate.schema.formatVersion)
+        reintrospection.push("schema-format-changed");
+    compare(reference.schema.hash, candidate.schema.hash, "schema-changed", reanalysis);
+    compare(reference.typePolicyHash, candidate.typePolicyHash, "type-policy-changed", reanalysis);
+    compare(reference.runtimeSettingsHash, candidate.runtimeSettingsHash, "runtime-settings-changed", reintrospection);
+    compare(reference.source?.hash, candidate.source?.hash, "source-changed", reanalysis);
+    compare(reference.source?.query, candidate.source?.query, "query-changed", reanalysis);
+    const [outcome, reasons] = unsupported.length > 0
+        ? ["unsupported-target", unsupported]
+        : reintrospection.length > 0
+            ? ["requires-reintrospection", reintrospection]
+            : reanalysis.length > 0
+                ? ["requires-reanalysis", reanalysis]
+                : ["compatible", []];
+    return Object.freeze({ outcome, reasons: Object.freeze(reasons), candidate });
+}
+//# sourceMappingURL=artifact-compatibility.js.map

package/dist/packages/core/src/artifact-compatibility.js.map

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

package/dist/packages/core/src/debug.d.ts

@@ -0,0 +1,39 @@
+export declare const SUPPORT_BUNDLE_FORMAT_VERSION: 1;
+export interface DebugRedactionOptions {
+    readonly includeSql?: boolean;
+    readonly includeIdentifiers?: boolean;
+    readonly includePaths?: boolean;
+    readonly includeDebugText?: boolean;
+}
+export interface DebugEventInput {
+    readonly phase: string;
+    readonly event: string;
+    readonly durationMilliseconds?: number;
+    readonly cache?: Readonly<Record<string, number>>;
+    readonly capability?: string;
+    readonly failure?: {
+        readonly code: string;
+        readonly classification: string;
+    };
+    readonly context?: unknown;
+}
+export interface DebugEvent extends Omit<DebugEventInput, "context"> {
+    readonly context?: unknown;
+}
+export interface SupportBundle {
+    readonly formatVersion: typeof SUPPORT_BUNDLE_FORMAT_VERSION;
+    readonly redaction: "default";
+    readonly inventory: {
+        readonly eventCount: number;
+        readonly phases: readonly string[];
+        readonly events: readonly string[];
+        readonly contextIncluded: boolean;
+    };
+    readonly environment: unknown;
+    readonly events: readonly DebugEvent[];
+}
+export declare function redactDebugContext(value: unknown, options?: DebugRedactionOptions): unknown;
+export declare function createDebugEvent(input: DebugEventInput, options?: DebugRedactionOptions): DebugEvent;
+export declare function createSupportBundle(events: readonly DebugEventInput[], environment?: unknown): SupportBundle;
+export declare function serializeSupportBundle(bundle: SupportBundle): string;
+//# sourceMappingURL=debug.d.ts.map

package/dist/packages/core/src/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../../../src/debug.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,6BAA6B,EAAG,CAAU,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,EAAE,OAAO,6BAA6B,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;KACnC,CAAC;IACF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;CACxC;AAsCD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAE/F;AAOD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,GAAE,qBAA0B,GAAG,UAAU,CA2BxG;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,EAAE,WAAW,GAAE,OAAY,GAAG,aAAa,CAchH;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,CAEpE"}

package/dist/packages/core/src/debug.js

@@ -0,0 +1,87 @@
+export const SUPPORT_BUNDLE_FORMAT_VERSION = 1;
+const sensitiveKey = /(?:authorization|cookie|credential|password|secret|token|connection|string|dsn|parameter|params|values?)/iu;
+const sqlKey = /(?:sql|query|source|statement|text)/iu;
+const identifierKey = /(?:identifier|table|column|schema|relation|namespace)/iu;
+const pathKey = /(?:file|path|cwd|root|uri|directory)/iu;
+const safeTextKey = /^(?:backend|capability|category|classification|code|event|kind|operation|phase|releaseTrack|status|support|version)$/u;
+function redact(value, options, key, seen, depth) {
+    if (depth > 8)
+        return "[redacted:depth-limit]";
+    if (sensitiveKey.test(key))
+        return "[redacted:sensitive]";
+    if (sqlKey.test(key) && options.includeSql !== true)
+        return "[redacted:sql]";
+    if (identifierKey.test(key) && options.includeIdentifiers !== true)
+        return "[redacted:identifier]";
+    if (pathKey.test(key) && options.includePaths !== true)
+        return "[redacted:path]";
+    if (value === null || typeof value === "boolean" || typeof value === "number")
+        return typeof value === "number" && !Number.isFinite(value) ? "[redacted:non-json-number]" : value;
+    if (typeof value === "string")
+        return options.includeDebugText === true || safeTextKey.test(key) ? value : "[redacted:text]";
+    if (typeof value !== "object")
+        return `[redacted:${typeof value}]`;
+    if (seen.has(value))
+        return "[redacted:cycle]";
+    seen.add(value);
+    if (Array.isArray(value))
+        return Object.freeze(value.slice(0, 256).map((item) => redact(item, options, key, seen, depth + 1)));
+    const entries = Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .slice(0, 256)
+        .map(([name, item]) => [name, redact(item, options, name, seen, depth + 1)]);
+    return Object.freeze(Object.fromEntries(entries));
+}
+export function redactDebugContext(value, options = {}) {
+    return redact(value, options, "context", new WeakSet(), 0);
+}
+function requiredText(value, path) {
+    if (typeof value !== "string" || value.length === 0)
+        throw new TypeError(`${path} must be a non-empty string`);
+    return value;
+}
+export function createDebugEvent(input, options = {}) {
+    const phase = requiredText(input.phase, "Debug event phase");
+    const event = requiredText(input.event, "Debug event name");
+    if (input.durationMilliseconds !== undefined &&
+        (!Number.isFinite(input.durationMilliseconds) || input.durationMilliseconds < 0)) {
+        throw new TypeError("Debug event durationMilliseconds must be a non-negative finite number");
+    }
+    return Object.freeze({
+        phase,
+        event,
+        ...(input.durationMilliseconds === undefined ? {} : { durationMilliseconds: input.durationMilliseconds }),
+        ...(input.cache === undefined
+            ? {}
+            : { cache: redactDebugContext(input.cache) }),
+        ...(input.capability === undefined ? {} : { capability: requiredText(input.capability, "Debug event capability") }),
+        ...(input.failure === undefined
+            ? {}
+            : {
+                failure: Object.freeze({
+                    code: requiredText(input.failure.code, "Debug event failure code"),
+                    classification: requiredText(input.failure.classification, "Debug event failure classification"),
+                }),
+            }),
+        ...(input.context === undefined ? {} : { context: redactDebugContext(input.context, options) }),
+    });
+}
+export function createSupportBundle(events, environment = {}) {
+    const redactedEvents = Object.freeze(events.map((event) => createDebugEvent(event)));
+    return Object.freeze({
+        formatVersion: SUPPORT_BUNDLE_FORMAT_VERSION,
+        redaction: "default",
+        inventory: Object.freeze({
+            eventCount: redactedEvents.length,
+            phases: Object.freeze([...new Set(redactedEvents.map(({ phase }) => phase))].sort()),
+            events: Object.freeze([...new Set(redactedEvents.map(({ event }) => event))].sort()),
+            contextIncluded: redactedEvents.some(({ context }) => context !== undefined),
+        }),
+        environment: redactDebugContext(environment),
+        events: redactedEvents,
+    });
+}
+export function serializeSupportBundle(bundle) {
+    return `${JSON.stringify(bundle, null, 2)}\n`;
+}
+//# sourceMappingURL=debug.js.map

package/dist/packages/core/src/debug.js.map

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