@impetik/xeer-mcp 0.2.5 → 0.2.7

package/vendor/spec/public-assets.js

@@ -0,0 +1,166 @@
+/**
+ * Deliberately free of imports. The control plane and the dispatcher are Workers, and this module is
+ * the one piece of the contract they both need; pulling in `canonical.ts` would drag `node:crypto`
+ * across that boundary for the sake of a helper neither of them calls.
+ */
+export const PUBLIC_ASSETS_FORMAT = 'xeer.assets.v0';
+/**
+ * The one prefix under which a URL *is* a content address, and which no application may occupy.
+ *
+ * It does **not** bypass the dispatcher — every request to a deployed application is routed through
+ * it, so a cold asset request still pays origin resolution and authorization. What a dedicated
+ * prefix buys is narrower and worth stating exactly: it stays clear of `/_xeer/*` (dispatcher) and
+ * `/__xeer/*` (runtime), both of which are claimed before the assets are consulted; it gives the
+ * `_headers` rule an exclusive namespace, so the immutable directive can never reach a mutable path;
+ * and it gives the deployment somewhere to route a *miss*, which is what turns a stale reference into
+ * a 404 instead of the single-page-application fallback.
+ */
+export const IMMUTABLE_ASSET_PREFIX = '/_xa/';
+/**
+ * What a hashed path is served with, and the reason the naming scheme exists at all.
+ *
+ * `immutable` (RFC 8246) tells a browser not to revalidate on an ordinary reload; a force reload
+ * still revalidates, so this does not cost anyone a debugging tool. It is only ever safe because the
+ * URL is a digest of the bytes — the same URL can never legitimately answer with anything else — and
+ * that is why {@link immutableAssetPath} is the only sanctioned way to mint one.
+ */
+export const IMMUTABLE_ASSET_CACHE_CONTROL = 'public, max-age=31536000, immutable';
+/**
+ * How much of the digest goes into the URL: all of it.
+ *
+ * A truncated digest was the first design and it was wrong. The argument for it — that collisions are
+ * inconceivable across one application's three generated files — answers the wrong question. The
+ * threat model includes attacker-influenced bytes, and against a *constructed* pair the bound is the
+ * birthday bound over the retained prefix, not the second-preimage bound over the whole digest. At
+ * 128 bits that is 2^64 work to mint two files sharing a URL, one of which then inherits a one-year
+ * `immutable` cache entry that no later deployment can withdraw. Thirty-two more characters of URL is
+ * not a price worth arguing about against that.
+ *
+ * It also makes a property the rest of the system leans on actually true: equal paths imply equal
+ * bytes.
+ */
+export const IMMUTABLE_ASSET_HASH_LENGTH = 64;
+/**
+ * Upper bound on {@link PublicAssetsV0.retainedGenerations}.
+ *
+ * One, because one is what the control plane implements. A wider range was declared first and that
+ * was a promise the code did not keep: an artifact could ask for four generations and silently get
+ * one. A contract that can express a value nothing honours is worse than a narrow contract.
+ */
+export const MAX_RETAINED_ASSET_GENERATIONS = 1;
+const IMMUTABLE_PATH = /^\/_xa\/[0-9a-f]{64}\/[A-Za-z0-9](?:[A-Za-z0-9._-]{0,63})$/u;
+const ASSET_HASH = /^sha256:[0-9a-f]{64}$/u;
+/** The URL a blob of bytes is served at, and the only sanctioned way to mint one. */
+export function immutableAssetPath(hash, basename) {
+    return `${IMMUTABLE_ASSET_PREFIX}${hash.slice('sha256:'.length, 'sha256:'.length + IMMUTABLE_ASSET_HASH_LENGTH)}/${basename}`;
+}
+/**
+ * A cheap structural pre-filter, and never the authority. Membership of
+ * {@link PublicAssetsV0.immutable} is what makes a path immutable; this only rejects the
+ * overwhelming majority of traffic before anything more expensive is consulted.
+ */
+export function isImmutableAssetPath(path) {
+    return IMMUTABLE_PATH.test(path);
+}
+/**
+ * The `_headers` document Cloudflare's static asset layer applies to a deployment.
+ *
+ * One rule, scoped to the prefix. Nothing else may appear here: an `immutable` directive that leaked
+ * onto the HTML document would pin stale markup in every browser that saw it for a year, and no
+ * server-side action reaches a browser that has already stored one.
+ */
+export function immutableAssetHeaders(prefix = IMMUTABLE_ASSET_PREFIX) {
+    return `${prefix}*\n  Cache-Control: ${IMMUTABLE_ASSET_CACHE_CONTROL}\n`;
+}
+function fail(message) {
+    throw new TypeError(`publicAssets: ${message}`);
+}
+function object(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        fail(`${label} must be an object.`);
+    return value;
+}
+function origin(value, label) {
+    // The `:` must be followed by something. An empty `module:` names nothing, and `documentReferences`
+    // resolves the document's three subresources by matching on this exact string.
+    if (typeof value !== 'string' || value.length > 256
+        || !(value === 'document' || /^(?:module|asset):.+$/u.test(value))) {
+        fail(`${label}.origin must be "document", "module:<path>" or "asset:<path>".`);
+    }
+    return value;
+}
+function contentType(value, label) {
+    if (typeof value !== 'string' || !/^[\x20-\x7e]{1,128}$/u.test(value))
+        fail(`${label}.contentType is invalid.`);
+    return value;
+}
+function sorted(paths, label) {
+    for (let index = 1; index < paths.length; index += 1) {
+        // `<=` rather than `<`: a duplicate is caught by the same comparison that catches disorder,
+        // because both mean the list is not the canonical enumeration of a set.
+        if (paths[index - 1] >= paths[index])
+            fail(`${label} must be sorted by path and free of duplicates.`);
+    }
+}
+/**
+ * Validates a declaration rather than trusting one. Every rule below has a failure it exists to
+ * prevent, and the two that matter most are the last two:
+ *
+ * - **path–hash binding.** If a hashed path could ever name bytes other than its own digest, the
+ *   immutable cache directive becomes unsafe and there is no way to withdraw it.
+ * - **prefix exclusivity.** If anything mutable could answer under the prefix, the single `_headers`
+ *   rule would make it permanently cacheable too.
+ */
+export function parsePublicAssets(value) {
+    const input = object(value, 'declaration');
+    if (input.format !== PUBLIC_ASSETS_FORMAT)
+        fail(`format must be ${PUBLIC_ASSETS_FORMAT}.`);
+    if (input.immutablePrefix !== IMMUTABLE_ASSET_PREFIX)
+        fail(`immutablePrefix must be ${IMMUTABLE_ASSET_PREFIX}.`);
+    const retainedGenerations = input.retainedGenerations;
+    if (typeof retainedGenerations !== 'number' || !Number.isInteger(retainedGenerations)
+        || retainedGenerations < 0 || retainedGenerations > MAX_RETAINED_ASSET_GENERATIONS) {
+        fail(`retainedGenerations must be an integer between 0 and ${MAX_RETAINED_ASSET_GENERATIONS}.`);
+    }
+    if (!Array.isArray(input.immutable) || !Array.isArray(input.revalidate))
+        fail('immutable and revalidate must be arrays.');
+    const immutable = input.immutable.map((item, index) => {
+        const entry = object(item, `immutable[${index}]`);
+        const hash = entry.hash;
+        if (typeof hash !== 'string' || !ASSET_HASH.test(hash))
+            fail(`immutable[${index}].hash is invalid.`);
+        const path = entry.path;
+        if (typeof path !== 'string' || !isImmutableAssetPath(path))
+            fail(`immutable[${index}].path is not a well-formed immutable path.`);
+        if (path !== immutableAssetPath(hash, path.slice(path.lastIndexOf('/') + 1))) {
+            fail(`immutable[${index}].path does not carry the digest of its own bytes.`);
+        }
+        const size = entry.size;
+        if (typeof size !== 'number' || !Number.isInteger(size) || size < 0)
+            fail(`immutable[${index}].size is invalid.`);
+        return { path, hash: hash, contentType: contentType(entry.contentType, `immutable[${index}]`),
+            size, origin: origin(entry.origin, `immutable[${index}]`) };
+    });
+    const revalidate = input.revalidate.map((item, index) => {
+        const entry = object(item, `revalidate[${index}]`);
+        const path = entry.path;
+        if (typeof path !== 'string' || !path.startsWith('/') || path.includes('//') || path.includes('..')) {
+            fail(`revalidate[${index}].path is invalid.`);
+        }
+        if (path.startsWith(IMMUTABLE_ASSET_PREFIX))
+            fail(`revalidate[${index}].path uses the reserved immutable prefix.`);
+        return { path, contentType: contentType(entry.contentType, `revalidate[${index}]`),
+            origin: origin(entry.origin, `revalidate[${index}]`) };
+    });
+    sorted(immutable.map((entry) => entry.path), 'immutable');
+    sorted(revalidate.map((entry) => entry.path), 'revalidate');
+    return { format: PUBLIC_ASSETS_FORMAT, immutablePrefix: IMMUTABLE_ASSET_PREFIX, retainedGenerations,
+        immutable, revalidate };
+}
+/**
+ * Every path that must answer for this deployment, immutable first. The union a control plane uploads
+ * is this set for the current artifact plus the immutable half of the retained generations.
+ */
+export function declaredAssetPaths(declaration) {
+    return [...declaration.immutable.map((entry) => entry.path), ...declaration.revalidate.map((entry) => entry.path)];
+}

package/vendor/spec/review.d.ts

@@ -0,0 +1,120 @@
+import type { NormalizedDatabaseSchemaV0, SchemaPlanV0 } from './schema-plan.js';
+import { type ApplicationArtifactV0, type ApplicationSchemaIdentityV0, type Capability, type SourceReceipt } from './types.js';
+export declare const ARTIFACT_REVIEW_PROTOCOL: "xeer.artifact-review.v0";
+export declare const TEST_EVIDENCE_PROTOCOL: "xeer.test-evidence.v0";
+export declare const REVIEW_PROTOCOL: "xeer.review.v0";
+export declare const REVIEW_RECEIPT_ID_SOURCE: "^review_[A-Za-z0-9_-]{12,96}$";
+export declare const REVIEW_RECEIPT_ID_PATTERN: RegExp;
+export interface ArtifactReviewMetadataV0 {
+    readonly protocol: typeof ARTIFACT_REVIEW_PROTOCOL;
+    readonly sourceHash: `sha256:${string}`;
+    readonly schema: NormalizedDatabaseSchemaV0;
+    readonly schemaIdentity: ApplicationSchemaIdentityV0;
+}
+export type TestEvidenceStatus = 'passed' | 'failed';
+/** A local test runner's report. The control plane records it as reported evidence, not an attestation. */
+export interface XeerTestEvidenceV0 {
+    readonly protocol: typeof TEST_EVIDENCE_PROTOCOL;
+    readonly artifactId: `sha256:${string}`;
+    readonly status: TestEvidenceStatus;
+    readonly reason: string;
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly files: readonly string[];
+    readonly completedAt: string;
+}
+export interface ReviewTestEvidenceV0 {
+    readonly provenance: 'reported' | 'absent';
+    readonly status: TestEvidenceStatus | 'absent';
+    readonly reason: string;
+    readonly total: number;
+    readonly passed: number;
+    readonly failed: number;
+    readonly completedAt: string | null;
+}
+export interface ReviewSchemaChangeV0 {
+    readonly status: 'unknown' | 'initial' | 'unchanged' | 'planned' | 'unplannable';
+    readonly from: ApplicationSchemaIdentityV0 | null;
+    readonly to: ApplicationSchemaIdentityV0 | null;
+    readonly plan: SchemaPlanV0 | null;
+    readonly planningError: string | null;
+}
+export interface ReviewCapabilityChangeV0 {
+    readonly before: readonly Capability[];
+    readonly after: readonly Capability[];
+    readonly added: readonly Capability[];
+    readonly removed: readonly Capability[];
+}
+export interface ReviewEnvironmentNamesV0 {
+    readonly preview: readonly string[];
+    readonly production: readonly string[];
+    readonly previewOnly: readonly string[];
+    readonly productionOnly: readonly string[];
+}
+export interface XeerReviewReceiptV0 {
+    readonly protocol: typeof REVIEW_PROTOCOL;
+    readonly receiptId: string;
+    readonly appId: string;
+    readonly application: string;
+    readonly artifactId: `sha256:${string}`;
+    readonly sourceHash: `sha256:${string}` | null;
+    readonly createdAt: string;
+    readonly test: ReviewTestEvidenceV0;
+    readonly changes: {
+        readonly baselineArtifactId: `sha256:${string}` | null;
+        readonly schema: ReviewSchemaChangeV0;
+        readonly capabilities: ReviewCapabilityChangeV0;
+        readonly environmentNames: ReviewEnvironmentNamesV0;
+    };
+    readonly preview: {
+        readonly deploymentId: string;
+        readonly url: string;
+    };
+}
+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;
+export declare function isReviewReceiptId(value: string): boolean;
+export declare function capabilityChange(before: readonly string[], after: readonly string[]): ReviewCapabilityChangeV0;
+export declare function environmentNameChange(preview: readonly string[], production: readonly string[]): ReviewEnvironmentNamesV0;

package/vendor/spec/review.js

@@ -0,0 +1,226 @@
+import { z } from 'zod';
+import { canonicalHash } from './canonical.js';
+import { normalizedDatabaseSchema } from './schema.js';
+import { applicationSchemaIdentity } from './schema-lifecycle.js';
+import { CAPABILITIES, } from './types.js';
+export const ARTIFACT_REVIEW_PROTOCOL = 'xeer.artifact-review.v0';
+export const TEST_EVIDENCE_PROTOCOL = 'xeer.test-evidence.v0';
+export const REVIEW_PROTOCOL = 'xeer.review.v0';
+export const REVIEW_RECEIPT_ID_SOURCE = '^review_[A-Za-z0-9_-]{12,96}$';
+export const REVIEW_RECEIPT_ID_PATTERN = new RegExp(REVIEW_RECEIPT_ID_SOURCE, 'u');
+const HASH = /^sha256:[a-f0-9]{64}$/u;
+const APP_ID = /^app_[A-Za-z0-9_-]{8,96}$/u;
+const schemaIdentity = z.strictObject({
+    applicationSchemaVersion: z.number().int().positive(),
+    schemaHash: z.string().regex(HASH),
+});
+const artifactReview = z.strictObject({
+    protocol: z.literal(ARTIFACT_REVIEW_PROTOCOL),
+    sourceHash: z.string().regex(HASH),
+    schema: normalizedDatabaseSchema,
+    schemaIdentity,
+});
+const testEvidence = z.strictObject({
+    protocol: z.literal(TEST_EVIDENCE_PROTOCOL),
+    artifactId: z.string().regex(HASH),
+    status: z.enum(['passed', 'failed']),
+    reason: z.string().min(1).max(64),
+    total: z.number().int().nonnegative(),
+    passed: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    files: z.array(z.string().min(1).max(512)).max(512),
+    completedAt: z.iso.datetime(),
+}).superRefine((value, context) => {
+    if (value.passed + value.failed !== value.total) {
+        context.addIssue({ code: 'custom', path: ['total'], message: 'must equal passed + failed' });
+    }
+    if (value.status === 'passed' && (value.total === 0 || value.failed !== 0)) {
+        context.addIssue({ code: 'custom', path: ['status'], message: 'requires at least one test and zero failures' });
+    }
+    if (value.status === 'failed' && value.failed === 0 && value.reason === 'complete') {
+        context.addIssue({ code: 'custom', path: ['status'], message: 'failed evidence needs a failure reason' });
+    }
+});
+const schemaPlanStep = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('table.add'), table: z.string().min(1) }),
+    z.strictObject({ kind: z.literal('table.remove'), table: z.string().min(1) }),
+    z.strictObject({ kind: z.literal('field.add'), table: z.string().min(1), field: z.string().min(1),
+        optional: z.boolean() }),
+    z.strictObject({ kind: z.literal('field.remove'), table: z.string().min(1), field: z.string().min(1) }),
+    z.strictObject({ kind: z.literal('field.type'), table: z.string().min(1), field: z.string().min(1),
+        from: z.enum(['string', 'number', 'boolean', 'datetime', 'bytes', 'json']),
+        to: z.enum(['string', 'number', 'boolean', 'datetime', 'bytes', 'json']) }),
+    z.strictObject({ kind: z.literal('field.optional'), table: z.string().min(1), field: z.string().min(1),
+        from: z.boolean(), to: z.boolean() }),
+    z.strictObject({ kind: z.literal('field.maxLength'), table: z.string().min(1), field: z.string().min(1),
+        from: z.number().int().positive().nullable(), to: z.number().int().positive().nullable() }),
+    z.strictObject({ kind: z.literal('index.add'), table: z.string().min(1), index: z.string().min(1),
+        fields: z.array(z.string().min(1)) }),
+    z.strictObject({ kind: z.literal('index.remove'), table: z.string().min(1), index: z.string().min(1),
+        fields: z.array(z.string().min(1)) }),
+    z.strictObject({ kind: z.literal('index.change'), table: z.string().min(1), index: z.string().min(1),
+        from: z.array(z.string().min(1)), to: z.array(z.string().min(1)) }),
+    z.strictObject({ kind: z.literal('unknown.change'), path: z.string().min(1) }),
+]);
+const schemaPlan = z.strictObject({
+    protocol: z.literal('xeer.schema.v0'),
+    application: z.string().min(1),
+    from: schemaIdentity,
+    to: schemaIdentity,
+    classification: z.enum(['unchanged', 'compatible', 'incompatible']),
+    steps: z.array(schemaPlanStep),
+    requiresReset: z.boolean(),
+});
+const reviewReceipt = z.strictObject({
+    protocol: z.literal(REVIEW_PROTOCOL),
+    receiptId: z.string().regex(REVIEW_RECEIPT_ID_PATTERN),
+    appId: z.string().regex(APP_ID),
+    application: z.string().min(1),
+    artifactId: z.string().regex(HASH),
+    sourceHash: z.string().regex(HASH).nullable(),
+    createdAt: z.iso.datetime(),
+    test: z.strictObject({
+        provenance: z.enum(['reported', 'absent']),
+        status: z.enum(['passed', 'failed', 'absent']),
+        reason: z.string().min(1).max(64),
+        total: z.number().int().nonnegative(),
+        passed: z.number().int().nonnegative(),
+        failed: z.number().int().nonnegative(),
+        completedAt: z.iso.datetime().nullable(),
+    }),
+    changes: z.strictObject({
+        baselineArtifactId: z.string().regex(HASH).nullable(),
+        schema: z.strictObject({
+            status: z.enum(['unknown', 'initial', 'unchanged', 'planned', 'unplannable']),
+            from: schemaIdentity.nullable(),
+            to: schemaIdentity.nullable(),
+            plan: schemaPlan.nullable(),
+            planningError: z.string().nullable(),
+        }),
+        capabilities: z.strictObject({
+            before: z.array(z.enum(CAPABILITIES)), after: z.array(z.enum(CAPABILITIES)),
+            added: z.array(z.enum(CAPABILITIES)), removed: z.array(z.enum(CAPABILITIES)),
+        }),
+        environmentNames: z.strictObject({
+            preview: z.array(z.string().min(1)), production: z.array(z.string().min(1)),
+            previewOnly: z.array(z.string().min(1)), productionOnly: z.array(z.string().min(1)),
+        }),
+    }),
+    preview: z.strictObject({ deploymentId: z.string().min(1), url: z.url() }),
+}).superRefine((value, context) => {
+    if (value.test.passed + value.test.failed !== value.test.total) {
+        context.addIssue({ code: 'custom', path: ['test', 'total'], message: 'must equal passed + failed' });
+    }
+    if (value.test.provenance === 'absent'
+        && (value.test.status !== 'absent' || value.test.total !== 0 || value.test.completedAt !== null)) {
+        context.addIssue({ code: 'custom', path: ['test'], message: 'absent evidence must contain no results' });
+    }
+    if (value.test.provenance === 'reported' && value.test.completedAt === null) {
+        context.addIssue({ code: 'custom', path: ['test', 'completedAt'], message: 'reported evidence needs a time' });
+    }
+    if (value.test.status === 'passed' && (value.test.total === 0 || value.test.failed !== 0)) {
+        context.addIssue({ code: 'custom', path: ['test', 'status'], message: 'requires tests and zero failures' });
+    }
+});
+export function artifactSourceHash(files) {
+    return canonicalHash([...files]
+        .map(({ path, size, hash }) => ({ path, size, hash }))
+        .sort((left, right) => left.path.localeCompare(right.path)));
+}
+export function artifactReviewMetadata(artifact) {
+    return Object.freeze({
+        protocol: ARTIFACT_REVIEW_PROTOCOL,
+        sourceHash: artifactSourceHash(artifact.source.files),
+        schema: artifact.schema,
+        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 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 ArtifactReviewError({ code: 'artifact_review_schema_identity_mismatch', expected, received: parsed.schemaIdentity }, 'Artifact review schemaIdentity does not match its normalized schema.');
+    }
+    return parsed;
+}
+export function parseTestEvidence(value) {
+    return testEvidence.parse(value);
+}
+export function parseReviewReceipt(value) {
+    return reviewReceipt.parse(value);
+}
+export function isReviewReceiptId(value) {
+    return REVIEW_RECEIPT_ID_PATTERN.test(value);
+}
+export function capabilityChange(before, after) {
+    const prior = [...new Set(before)].filter((name) => CAPABILITIES.includes(name)).sort();
+    const next = [...new Set(after)].filter((name) => CAPABILITIES.includes(name)).sort();
+    return Object.freeze({
+        before: prior,
+        after: next,
+        added: next.filter((name) => !prior.includes(name)),
+        removed: prior.filter((name) => !next.includes(name)),
+    });
+}
+export function environmentNameChange(preview, production) {
+    const previewNames = [...new Set(preview)].sort();
+    const productionNames = [...new Set(production)].sort();
+    return Object.freeze({
+        preview: previewNames,
+        production: productionNames,
+        previewOnly: previewNames.filter((name) => !productionNames.includes(name)),
+        productionOnly: productionNames.filter((name) => !previewNames.includes(name)),
+    });
+}

package/vendor/spec/route.d.ts

@@ -0,0 +1,43 @@
+export declare const ENDPOINT_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"];
+export type EndpointMethod = typeof ENDPOINT_METHODS[number];
+export interface EndpointRoute {
+    readonly key: string;
+    readonly method: EndpointMethod;
+    readonly path: string;
+    /** Dynamic parameter names are erased so equivalent route shapes collide. */
+    readonly shape: string;
+}
+export declare function parseEndpointRoute(key: string): EndpointRoute | null;
+export declare function endpointRouteIdentity(route: Pick<EndpointRoute, 'method' | 'shape'>): string;
+export declare function endpointRouteMatches(route: Pick<EndpointRoute, 'method' | 'path'>, method: string, pathname: string): boolean;
+export declare function normalizeEndpointRoutes(keys: Iterable<string>): EndpointRoute[];
+/**
+ * The reserved runtime route that serves the live invalidation stream.
+ *
+ * `packages/runtime/src/live.ts` is normative for this path; this is a mirror, exactly as the SDK's
+ * `live.ts` already mirrors it. It is restated here rather than imported because the public
+ * dispatcher needs it and `xeer-auth` does not — and must not — depend on the runtime package: the
+ * dispatcher is a separate Worker, and an import edge would pull the whole application runtime into
+ * it to learn one string.
+ */
+export declare const LIVE_STREAM_PATH = "/__xeer/events";
+/**
+ * Every `/__xeer/` path a public visitor may reach. **A closed allowlist, and it has to stay one.**
+ *
+ * The public dispatcher refuses anything under `/__xeer/` that is not listed here. That is the
+ * inversion of an exact-path denylist, which was safe only for as long as nobody added a route: a
+ * new builder-only surface in the runtime was publicly reachable the moment it existed, and nothing
+ * in its own diff said so. Enumerating what is *open* means the default for a route nobody has
+ * written yet is closed.
+ *
+ * The obvious alternative — refusing the whole `/__xeer/` prefix — is wrong, because the application
+ * protocol lives under it: `rpc/query`, `rpc/mutation` and the live stream are how an application is
+ * used at all. `health` and `identity` are the two readiness probes, deliberately excluded from the
+ * runtime's own `INSPECTOR_ROUTES` so that deploys and uptime checks keep working.
+ *
+ * Adding an entry here makes a route publicly reachable on every deployed application. Nothing else
+ * does, which is the point: the decision is visible in one diff, in one place.
+ */
+export declare const PUBLIC_RESERVED_ROUTES: ReadonlySet<string>;
+/** Whether a path is reserved by the platform, and therefore governed by the allowlist above. */
+export declare function reservedRuntimePath(pathname: string): boolean;

package/vendor/spec/route.js

@@ -0,0 +1,87 @@
+export const ENDPOINT_METHODS = [
+    'GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD',
+];
+const METHODS = new Set(ENDPOINT_METHODS);
+const STATIC_SEGMENT = /^[A-Za-z0-9_.-]+$/;
+const PARAMETER_SEGMENT = /^:[A-Za-z][A-Za-z0-9_]*$/;
+export function parseEndpointRoute(key) {
+    const separator = key.indexOf(' ');
+    if (separator <= 0 || key.indexOf(' ', separator + 1) !== -1)
+        return null;
+    const method = key.slice(0, separator);
+    const path = key.slice(separator + 1);
+    if (!METHODS.has(method) || (path !== '/api' && !path.startsWith('/api/')))
+        return null;
+    const segments = path.split('/').slice(2);
+    if (segments.some((segment) => !STATIC_SEGMENT.test(segment) && !PARAMETER_SEGMENT.test(segment)))
+        return null;
+    const shape = segments.length === 0
+        ? '/api'
+        : `/api/${segments.map((segment) => segment.startsWith(':') ? ':' : segment).join('/')}`;
+    return { key, method: method, path, shape };
+}
+export function endpointRouteIdentity(route) {
+    return `${route.method} ${route.shape}`;
+}
+export function endpointRouteMatches(route, method, pathname) {
+    if (route.method !== method)
+        return false;
+    const expected = route.path.split('/');
+    const actual = pathname.split('/');
+    return expected.length === actual.length && expected.every((part, index) => part.startsWith(':') ? (actual[index]?.length ?? 0) > 0 : part === actual[index]);
+}
+export function normalizeEndpointRoutes(keys) {
+    const routes = [];
+    const identities = new Map();
+    for (const key of keys) {
+        const route = parseEndpointRoute(key);
+        if (!route)
+            throw new Error(`Invalid endpoint route: ${key}`);
+        const identity = endpointRouteIdentity(route);
+        const existing = identities.get(identity);
+        if (existing && existing !== route.key) {
+            throw new Error(`Ambiguous endpoint routes: ${existing} and ${route.key}`);
+        }
+        identities.set(identity, route.key);
+        routes.push(route);
+    }
+    return routes.sort((left, right) => left.key.localeCompare(right.key));
+}
+/**
+ * The reserved runtime route that serves the live invalidation stream.
+ *
+ * `packages/runtime/src/live.ts` is normative for this path; this is a mirror, exactly as the SDK's
+ * `live.ts` already mirrors it. It is restated here rather than imported because the public
+ * dispatcher needs it and `xeer-auth` does not — and must not — depend on the runtime package: the
+ * dispatcher is a separate Worker, and an import edge would pull the whole application runtime into
+ * it to learn one string.
+ */
+export const LIVE_STREAM_PATH = '/__xeer/events';
+/**
+ * Every `/__xeer/` path a public visitor may reach. **A closed allowlist, and it has to stay one.**
+ *
+ * The public dispatcher refuses anything under `/__xeer/` that is not listed here. That is the
+ * inversion of an exact-path denylist, which was safe only for as long as nobody added a route: a
+ * new builder-only surface in the runtime was publicly reachable the moment it existed, and nothing
+ * in its own diff said so. Enumerating what is *open* means the default for a route nobody has
+ * written yet is closed.
+ *
+ * The obvious alternative — refusing the whole `/__xeer/` prefix — is wrong, because the application
+ * protocol lives under it: `rpc/query`, `rpc/mutation` and the live stream are how an application is
+ * used at all. `health` and `identity` are the two readiness probes, deliberately excluded from the
+ * runtime's own `INSPECTOR_ROUTES` so that deploys and uptime checks keep working.
+ *
+ * Adding an entry here makes a route publicly reachable on every deployed application. Nothing else
+ * does, which is the point: the decision is visible in one diff, in one place.
+ */
+export const PUBLIC_RESERVED_ROUTES = new Set([
+    '/__xeer/health',
+    '/__xeer/identity',
+    '/__xeer/rpc/query',
+    '/__xeer/rpc/mutation',
+    LIVE_STREAM_PATH,
+]);
+/** Whether a path is reserved by the platform, and therefore governed by the allowlist above. */
+export function reservedRuntimePath(pathname) {
+    return pathname.startsWith('/__xeer/') || pathname === '/__xeer';
+}