@impetik/xeer-mcp 0.2.6 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "type": "module",
   "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
   "license": "MIT",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.6"
+    "@impetik/xeer": "0.2.7"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"

package/vendor/spec/review.d.ts

@@ -74,6 +74,44 @@ export interface XeerReviewReceiptV0 {
 }
 export declare function artifactSourceHash(files: readonly SourceReceipt[]): `sha256:${string}`;
 export declare function artifactReviewMetadata(artifact: ApplicationArtifactV0): ArtifactReviewMetadataV0;
+/**
+ * Why review metadata was refused. The three cases look alike from the outside and are nothing alike
+ * to repair, which is what #205 cost an afternoon to: two of them are version skew between the build
+ * that produced the metadata and the build reading it, and only the third means the bundle is wrong.
+ */
+export type ArtifactReviewRejection = {
+    readonly code: 'artifact_review_malformed';
+    /**
+     * The failing paths within `artifactReview`, deduplicated, in the order they were reported —
+     * which is the order the payload declares them, and not sorted, because sorting shows `t1, t10,
+     * t2` and hides everything past the eighth lexicographic name.
+     *
+     * **Empty means the value is not an object of this protocol at all**, which is reported at the
+     * root where there is no field to name. It has no second meaning.
+     */
+    readonly fields: readonly string[];
+    /** Failing paths beyond the ones listed, so a truncated list never reads as a complete one. */
+    readonly omitted: number;
+} | {
+    /**
+     * Fields this build has never heard of. Skew, and the usual shape of it: a newer CLI emitting a
+     * schema key an older plane does not know reaches the strict object before any hash is compared,
+     * so it can only be told apart here.
+     */
+    readonly code: 'artifact_review_unknown_fields';
+    readonly fields: readonly string[];
+    readonly omitted: number;
+} | {
+    readonly code: 'artifact_review_schema_identity_mismatch';
+    /** What this build hashes the declared schema to. */
+    readonly expected: ApplicationSchemaIdentityV0;
+    /** What the metadata claims the same schema hashes to. */
+    readonly received: ApplicationSchemaIdentityV0;
+};
+export declare class ArtifactReviewError extends Error {
+    readonly rejection: ArtifactReviewRejection;
+    constructor(rejection: ArtifactReviewRejection, message: string);
+}
 export declare function parseArtifactReviewMetadata(value: unknown): ArtifactReviewMetadataV0;
 export declare function parseTestEvidence(value: unknown): XeerTestEvidenceV0;
 export declare function parseReviewReceipt(value: unknown): XeerReviewReceiptV0;

package/vendor/spec/review.js

@@ -135,12 +135,63 @@ export function artifactReviewMetadata(artifact) {
         schemaIdentity: artifact.schemaIdentity,
     });
 }
+export class ArtifactReviewError extends Error {
+    rejection;
+    constructor(rejection, message) {
+        super(message);
+        this.rejection = rejection;
+        this.name = 'ArtifactReviewError';
+    }
+}
+/** How many failing paths are worth showing a person, and how long one segment of one may be. */
+const REPORTED_PATHS = 8;
+const SEGMENT_LENGTH = 40;
+const PLAIN_SEGMENT = /^[A-Za-z0-9_$-]+$/u;
+/**
+ * One segment of a path, as it can safely be shown.
+ *
+ * A segment is not always ours: `tables` and `fields` are records keyed by caller-supplied names, so a
+ * table name arrives here verbatim. It is length-bounded because the rendered path reaches a 400 body
+ * and an operator's log, and quoted unless it is a plain name, because a table called `a.b` would
+ * otherwise read as two segments and send someone looking for a field that does not exist.
+ */
+function segment(value) {
+    const text = String(value);
+    const shown = text.length > SEGMENT_LENGTH ? `${text.slice(0, SEGMENT_LENGTH)}…` : text;
+    return PLAIN_SEGMENT.test(shown) ? shown : JSON.stringify(shown);
+}
+function renderPath(parts) {
+    return parts.map(segment).join('.');
+}
+/** The first {@link REPORTED_PATHS} of a deduplicated path list, with the count of the rest. */
+function reported(paths) {
+    const unique = [...new Set(paths)];
+    return { fields: unique.slice(0, REPORTED_PATHS), omitted: Math.max(0, unique.length - REPORTED_PATHS) };
+}
+/**
+ * The rejection a failed parse describes: unknown fields where that is the *only* complaint, and a
+ * malformed bundle otherwise. Requiring it to be the only complaint is deliberate — a payload that is
+ * both unrecognized and broken is broken, and calling it skew would point the repair at the wrong side.
+ */
+function parseRejection(error) {
+    if (error.issues.every((issue) => issue.code === 'unrecognized_keys')) {
+        return { code: 'artifact_review_unknown_fields',
+            ...reported(error.issues.flatMap((issue) => issue.code === 'unrecognized_keys'
+                ? issue.keys.map((key) => renderPath([...issue.path, key])) : [])) };
+    }
+    return { code: 'artifact_review_malformed',
+        ...reported(error.issues.map((issue) => renderPath(issue.path)).filter((path) => path !== '')) };
+}
 export function parseArtifactReviewMetadata(value) {
-    const parsed = artifactReview.parse(value);
+    const result = artifactReview.safeParse(value);
+    if (!result.success) {
+        throw new ArtifactReviewError(parseRejection(result.error), 'Artifact review metadata does not match xeer.artifact-review.v0.');
+    }
+    const parsed = result.data;
     const expected = applicationSchemaIdentity(parsed.schema);
     if (parsed.schemaIdentity.applicationSchemaVersion !== expected.applicationSchemaVersion
         || parsed.schemaIdentity.schemaHash !== expected.schemaHash) {
-        throw new TypeError('Artifact review schemaIdentity does not match its normalized schema.');
+        throw new ArtifactReviewError({ code: 'artifact_review_schema_identity_mismatch', expected, received: parsed.schemaIdentity }, 'Artifact review schemaIdentity does not match its normalized schema.');
     }
     return parsed;
 }

package/vendor/spec/schema-lifecycle.d.ts

@@ -3,4 +3,25 @@ import { type NormalizedDatabaseSchemaV0, type SchemaPlanV0 } from './schema-pla
 export * from './schema-plan.js';
 export declare function applicationSchemaHash(schema: NormalizedDatabaseSchemaV0): `sha256:${string}`;
 export declare function applicationSchemaIdentity(schema: NormalizedDatabaseSchemaV0): ApplicationSchemaIdentityV0;
+/** A fresh copy of the reference schema, so nothing that reads it can move the revision for everyone. */
+export declare function schemaIdentityReference(): NormalizedDatabaseSchemaV0;
+/**
+ * Which schema-identity projection *this build* computes, as the hash it gives the reference schema
+ * above.
+ *
+ * A schema hash is only an identity because two builds agree on it, and when they stop agreeing every
+ * symptom is somewhere else: the control plane refuses a `schemaIdentity` the CLI computed correctly
+ * for its own build, and the deployment reads as a malformed bundle (#205). Nothing about a version
+ * number settles it either way — a release can move the projection or leave it untouched — so the
+ * answer has to be a value derived from the projection itself. Two builds reporting the same revision
+ * hash the same schema to the same identity; two reporting different ones do not, and the older is the
+ * one to upgrade.
+ *
+ * Derived rather than declared, so it cannot be forgotten: adding, removing or renaming a key in
+ * `normalizedSchemaPayload` moves this hash in the same commit that moves it, because every key is
+ * emitted unconditionally and the reference declares one of each. What it cannot see is a change to how
+ * a value is *derived* for a shape the reference does not declare — index normalization has its own
+ * spellings, and only the ones written here are covered.
+ */
+export declare function schemaIdentityRevision(): `sha256:${string}`;
 export declare function planSchemaChange(application: string, fromSchema: NormalizedDatabaseSchemaV0, toSchema: NormalizedDatabaseSchemaV0): SchemaPlanV0;

package/vendor/spec/schema-lifecycle.js

@@ -54,6 +54,93 @@ export function applicationSchemaHash(schema) {
 export function applicationSchemaIdentity(schema) {
     return { applicationSchemaVersion: schema.version, schemaHash: applicationSchemaHash(schema) };
 }
+/**
+ * A fixed schema declaring one of everything the projection above reads, so that hashing it says which
+ * projection a build carries.
+ *
+ * Every attribute sits on a field named after it, which is what lets the test delete them one at a time
+ * and prove the revision notices. The declaration is a hash probe and not a manifest: `onDelete` and
+ * `onUpdate` need a `ref` field to sit on, so there are three of those, and nothing here is validated
+ * against the manifest rules because nothing here is ever deployed.
+ *
+ * Two properties of the *shape* are load-bearing, and both exist to close a way the revision could
+ * otherwise agree while the builds do not.
+ *
+ * **Two of everything the projection can iterate.** One table, one check, one index, one unique tuple
+ * would each let a projection that read only the first of them hash this schema exactly as a correct
+ * one does.
+ *
+ * **Every order-preserving array declared in an order sorting would change.** Object keys are sorted by
+ * canonical JSON and cannot carry order, but four arrays can and all four are semantic: an enum's
+ * values, the outer and inner arrays of a composite UNIQUE, and an index's columns — `UNIQUE (a, b)`
+ * and `UNIQUE (b, a)` build different indexes. A reference declaring a single unique tuple, or a tuple
+ * that happened to be in sorted order, would survive a future commit that started sorting them
+ * unchanged, while the hash of every real schema with two moved. Two builds would then compute
+ * different schema identities and report the *same* revision, and a `schema_identity_mismatch` would
+ * quote it as proof that they agree.
+ */
+const SCHEMA_IDENTITY_REFERENCE = {
+    version: 1,
+    tables: {
+        reference: {
+            fields: {
+                bytes: { type: 'bytes' },
+                collate: { type: 'string', collate: 'nocase' },
+                datetime: { type: 'datetime' },
+                default: { type: 'string', default: 'a' },
+                enum: { type: 'string', enum: ['b', 'a'] },
+                generated: { type: 'string', generated: { expression: 'lower(plain)', stored: true } },
+                json: { type: 'json' },
+                maxLength: { type: 'string', maxLength: 64 },
+                number: { type: 'number' },
+                onDelete: { type: 'ref', table: 'reference', onDelete: 'cascade' },
+                onUpdate: { type: 'ref', table: 'reference', onUpdate: 'restrict' },
+                optional: { type: 'string', optional: true },
+                plain: { type: 'string' },
+                table: { type: 'ref', table: 'reference' },
+                unique: { type: 'string', unique: true },
+            },
+            indexes: {
+                by_plain: ['plain'],
+                by_pair: ['plain', 'number'],
+                by_unique: { columns: [{ column: 'unique', desc: true }], unique: true, where: 'plain IS NOT NULL' },
+            },
+            unique: [['plain', 'number'], ['optional', 'maxLength']],
+            checks: { positive: 'number > 0', bounded: 'maxLength IS NOT NULL' },
+        },
+        beta: {
+            fields: { second: { type: 'string' }, first: { type: 'number' } },
+            indexes: { by_second: ['second'], by_first: ['first'] },
+            unique: [['second', 'first']],
+            checks: { nonzero: 'first <> 0', named: 'second <> \'\'' },
+        },
+    },
+};
+/** A fresh copy of the reference schema, so nothing that reads it can move the revision for everyone. */
+export function schemaIdentityReference() {
+    return structuredClone(SCHEMA_IDENTITY_REFERENCE);
+}
+/**
+ * Which schema-identity projection *this build* computes, as the hash it gives the reference schema
+ * above.
+ *
+ * A schema hash is only an identity because two builds agree on it, and when they stop agreeing every
+ * symptom is somewhere else: the control plane refuses a `schemaIdentity` the CLI computed correctly
+ * for its own build, and the deployment reads as a malformed bundle (#205). Nothing about a version
+ * number settles it either way — a release can move the projection or leave it untouched — so the
+ * answer has to be a value derived from the projection itself. Two builds reporting the same revision
+ * hash the same schema to the same identity; two reporting different ones do not, and the older is the
+ * one to upgrade.
+ *
+ * Derived rather than declared, so it cannot be forgotten: adding, removing or renaming a key in
+ * `normalizedSchemaPayload` moves this hash in the same commit that moves it, because every key is
+ * emitted unconditionally and the reference declares one of each. What it cannot see is a change to how
+ * a value is *derived* for a shape the reference does not declare — index normalization has its own
+ * spellings, and only the ones written here are covered.
+ */
+export function schemaIdentityRevision() {
+    return applicationSchemaHash(SCHEMA_IDENTITY_REFERENCE);
+}
 export function planSchemaChange(application, fromSchema, toSchema) {
     return planSchemaChangeWithIdentities(application, fromSchema, applicationSchemaIdentity(fromSchema), toSchema, applicationSchemaIdentity(toSchema));
 }