@assethub/cli 0.1.6 → 0.1.8

package/dist/runsUpload/buildRunUpload.js

@@ -0,0 +1,428 @@
+// Turn a local `ag.graph-folder.v1` run folder into an `ag.registry-push.v1`
+// envelope, and refuse to build one the server would reject.
+//
+// Port of assethub-ml research/artifact-graph/artifact-graph-py/
+// artifact_graph/registry/validation.py `snapshot_from_graph_folder` ->
+// `make_registry_snapshot` -> `_reference_only_manifest` / `_reference_only_blob`,
+// plus `service.py::make_push`.
+//
+// Two things this file is careful about:
+//
+//  - The wire form is *reference-only*. A folder's manifest blob table carries
+//    `file: "blobs/…"` so a reader can find the bytes on disk; the registry
+//    rejects any snapshot whose blob entries carry a path, URL or inline bytes
+//    (`INLINE_BLOB_FIELDS` in registry-worker/src/validation.js). The paths are
+//    kept out-of-band, on the plan, for the uploader to stream from.
+//
+//  - It validates locally what the server validates remotely. The expensive
+//    failure mode is a corrupt folder discovered *after* N blobs have already
+//    been uploaded, so every check that can be made from local bytes is made
+//    before the first request. `--dry-run` is exactly this function plus a
+//    report.
+import { stat } from 'node:fs/promises';
+import { canonicalGraphHash } from './artifactGraphModel.js';
+import { reachableBlobRefs } from './blobRefs.js';
+import { canonicalJson, isPlainObject, utf8ByteLength } from './canonicalJson.js';
+import { CONTROL_MAX_BLOB_BYTES, CONTROL_MAX_PUSH_BYTES, REGISTRY_MAX_GRAPH_ARRAY_BYTES, REGISTRY_MAX_MANIFEST_BYTES, } from './controlEndpoints.js';
+import { deriveFlows, deriveStates } from './graphFolder.js';
+import { RunUploadError } from './runUploadError.js';
+export const PUSH_SCHEMA_VERSION = 'ag.registry-push.v1';
+export const SNAPSHOT_SCHEMA_VERSION = 'ag.registry-snapshot.v1';
+export const GRAPH_FOLDER_SCHEMA_VERSION = 'ag.graph-folder.v1';
+export const SHARED_BLOB_STORE = 'shared-content-addressed';
+export const DEFAULT_GENERATOR = 'assethub-cli:runs.upload';
+const GRAPH_ID_RE = /^(?:graph_[A-Za-z0-9][A-Za-z0-9._:-]{0,121}|import_[A-Za-z0-9][A-Za-z0-9._:-]{0,120})$/;
+const GRAPH_HASH_RE = /^sha256:[0-9a-f]{64}$/;
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+const BLOB_REF_FIELDS = ['key', 'mime', 'size', 'sha256', 'name', 'artifactId', 'metadata'];
+const MANIFEST_FIELDS = [
+    'schemaVersion',
+    'createdAt',
+    'generator',
+    'selection',
+    'graph',
+    'blobStore',
+    'flows',
+    'states',
+    'blobs',
+    'missingBlobs',
+    'source',
+    'run',
+];
+// ISO-8601 date-time with an explicit offset, matching the worker's own
+// `dateTime()` accept set. A plain date, or a time without a zone, is rejected.
+const ISO_DATE_TIME_RE = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?(?:[Zz]|[+-]\d{2}:\d{2}(?::\d{2})?)$/;
+export const buildRunUploadPlan = async ({ folder, graphId: graphIdInput, streamId: streamIdInput, rev: revInput, description = '', tags = [], now = new Date(), }) => {
+    const warnings = [];
+    const manifest = folder.manifest;
+    const source = isPlainObject(manifest.source) ? manifest.source : null;
+    const graphId = validateGraphId(graphIdInput ?? defaultGraphId(folder.name), graphIdInput == null ? folder.name : undefined);
+    const streamId = validateStreamId(streamIdInput ?? defaultStreamId(source, graphId));
+    const rev = validateRev(revInput ?? asNonNegativeInteger(source?.rev) ?? 0);
+    const graph = folder.graph;
+    const graphHash = canonicalGraphHash(graph);
+    // --- manifest, rewritten reference-only -----------------------------------
+    rejectUnknownFields(manifest, MANIFEST_FIELDS, 'manifest.json');
+    const missingBlobs = manifest.missingBlobs;
+    if (Array.isArray(missingBlobs) && missingBlobs.length > 0) {
+        throw new RunUploadError('folder_incomplete', `This run folder is incomplete: manifest.missingBlobs lists ${missingBlobs.length} blob(s) whose bytes were never exported, ` +
+            'and Production Control only accepts a run whose every referenced blob is present. ' +
+            'Re-export the run with its blobs, then upload that folder.', { details: { blobKeys: missingBlobs.slice(0, 20) } });
+    }
+    const createdAt = manifestCreatedAt(manifest, now);
+    const generator = manifestGenerator(manifest);
+    if (isPlainObject(manifest.selection) && manifest.selection.kind !== 'whole-graph') {
+        // The reference implementation overwrites this unconditionally; matching it
+        // keeps the bytes identical, but a relabelled subgraph is worth saying out
+        // loud rather than shipping silently.
+        warnings.push(`manifest.selection.kind was ${JSON.stringify(manifest.selection.kind)}; ` +
+            'the snapshot declares selection {"kind":"whole-graph"}, so this upload will present the folder as a whole graph.');
+    }
+    // --- blobs ----------------------------------------------------------------
+    const declaredRaw = Array.isArray(manifest.blobs) ? manifest.blobs : [];
+    if (!Array.isArray(manifest.blobs)) {
+        throw new RunUploadError('manifest_blobs_invalid', 'manifest.json must carry a `blobs` array (the folder blob table).');
+    }
+    const declared = declaredRaw.map((entry, index) => {
+        if (!isPlainObject(entry)) {
+            throw new RunUploadError('manifest_blobs_invalid', `manifest.blobs[${index}] must be an object.`);
+        }
+        return referenceOnlyBlob(entry, index);
+    });
+    const seen = new Set();
+    for (const ref of declared) {
+        if (seen.has(ref.key)) {
+            throw new RunUploadError('manifest_blobs_invalid', `manifest.blobs declares the blob key ${ref.key} twice.`);
+        }
+        seen.add(ref.key);
+    }
+    declared.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const reachable = reachableBlobRefs(graph);
+    assertBlobSetsAgree(reachable, declared);
+    assertBlobMetadataAgrees(reachable, declared);
+    const nextManifest = {
+        ...manifest,
+        schemaVersion: GRAPH_FOLDER_SCHEMA_VERSION,
+        createdAt,
+        generator,
+        selection: { kind: 'whole-graph' },
+        graph: manifest.graph,
+        flows: deriveFlows(graph),
+        states: deriveStates(graph),
+        blobs: declared,
+        missingBlobs: [],
+    };
+    if ('blobStore' in nextManifest)
+        nextManifest.blobStore = SHARED_BLOB_STORE;
+    // --- the folder must still describe itself --------------------------------
+    assertManifestGraphMatches(manifest.graph, graph, graphHash, folder.path);
+    // --- sizes ----------------------------------------------------------------
+    const manifestBytes = utf8ByteLength(canonicalJson(nextManifest));
+    const nodesBytes = utf8ByteLength(canonicalJson(graph.nodes));
+    const edgesBytes = utf8ByteLength(canonicalJson(graph.edges));
+    assertUnderLimit('manifest', manifestBytes, REGISTRY_MAX_MANIFEST_BYTES);
+    assertUnderLimit('nodes', nodesBytes, REGISTRY_MAX_GRAPH_ARRAY_BYTES);
+    assertUnderLimit('edges', edgesBytes, REGISTRY_MAX_GRAPH_ARRAY_BYTES);
+    const snapshot = {
+        schemaVersion: SNAPSHOT_SCHEMA_VERSION,
+        graphId,
+        streamId,
+        rev,
+        graphHash,
+        blobStore: SHARED_BLOB_STORE,
+        manifest: nextManifest,
+        nodes: graph.nodes,
+        edges: graph.edges,
+        blobs: declared,
+    };
+    const push = {
+        schemaVersion: PUSH_SCHEMA_VERSION,
+        graphId,
+        streamId,
+        rev,
+        graphHash,
+        snapshot,
+    };
+    const pushBody = JSON.stringify(push);
+    const pushBytes = utf8ByteLength(pushBody);
+    if (pushBytes > CONTROL_MAX_PUSH_BYTES) {
+        throw new RunUploadError('push_too_large', `This run's snapshot is ${formatBytes(pushBytes)}, over the ${formatBytes(CONTROL_MAX_PUSH_BYTES)} Production Control accepts in one request ` +
+            `(${graph.nodes.length} nodes, ${graph.edges.length} edges). Nothing was sent. ` +
+            'Export a narrower selection of the run, or ask for the upload limit to be raised before retrying.', { details: { pushBytes, limitBytes: CONTROL_MAX_PUSH_BYTES } });
+    }
+    // --- the bytes each blob needs, checked but not read ----------------------
+    const blobs = await planBlobs(declared, folder);
+    return {
+        graphId,
+        streamId,
+        rev,
+        graphHash,
+        push,
+        pushBody,
+        blobs,
+        counts: {
+            nodes: graph.nodes.length,
+            edges: graph.edges.length,
+            blobs: blobs.length,
+            blobBytes: blobs.reduce((total, blob) => total + blob.size, 0),
+        },
+        sizes: { manifestBytes, nodesBytes, edgesBytes, pushBytes },
+        registration: {
+            graphId,
+            description,
+            tags: normalizeTags(tags),
+            metadata: registrationMetadata(folder, createdAt, generator),
+        },
+        warnings,
+    };
+};
+// ---------------------------------------------------------------------------
+// identity
+// ---------------------------------------------------------------------------
+/** `import_` rather than `graph_`: a local run folder is an import, not a graph
+ *  this deployment owns the authority for. */
+export const defaultGraphId = (folderName) => {
+    const slug = folderName
+        .replace(/[^A-Za-z0-9._:-]+/g, '-')
+        .replace(/^[^A-Za-z0-9]+/, '')
+        .slice(0, 121)
+        .replace(/-+$/, '');
+    if (!slug) {
+        throw new RunUploadError('graph_id_undeterminable', `Could not derive a graph id from the folder name ${JSON.stringify(folderName)}. Pass --graph-id import_<name> explicitly.`);
+    }
+    return `import_${slug}`;
+};
+const defaultStreamId = (source, graphId) => {
+    const authorityId = typeof source?.authorityId === 'string' ? source.authorityId.trim() : '';
+    return authorityId || `stream_cli_${graphId}`;
+};
+const validateGraphId = (value, derivedFrom) => {
+    if (!GRAPH_ID_RE.test(value)) {
+        throw new RunUploadError('invalid_graph_id', derivedFrom == null
+            ? `--graph-id must start with graph_ or import_ and then use only letters, digits, '.', '_', ':' or '-' (got ${JSON.stringify(value)}).`
+            : `The graph id derived from the folder name ${JSON.stringify(derivedFrom)} is not valid (${JSON.stringify(value)}). ` +
+                "It must start with graph_ or import_ and then use only letters, digits, '.', '_', ':' or '-'. Pass --graph-id to set it explicitly.");
+    }
+    return value;
+};
+const validateStreamId = (value) => {
+    if (typeof value !== 'string' || !value.trim() || value.length > 256) {
+        throw new RunUploadError('invalid_stream_id', '--stream-id must be a non-empty string of at most 256 characters.');
+    }
+    return value;
+};
+const validateRev = (value) => {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new RunUploadError('invalid_rev', '--rev must be a non-negative integer.');
+    }
+    return value;
+};
+// ---------------------------------------------------------------------------
+// manifest
+// ---------------------------------------------------------------------------
+const manifestCreatedAt = (manifest, now) => {
+    const raw = manifest.createdAt;
+    if (raw === undefined || raw === null || raw === '')
+        return isoNoMs(now);
+    if (typeof raw !== 'string' || !ISO_DATE_TIME_RE.test(raw)) {
+        throw new RunUploadError('manifest_created_at_invalid', `manifest.createdAt must be an ISO-8601 date-time including a timezone (got ${JSON.stringify(raw)}).`);
+    }
+    return raw;
+};
+const manifestGenerator = (manifest) => {
+    const raw = manifest.generator;
+    if (raw === undefined || raw === null || raw === '')
+        return DEFAULT_GENERATOR;
+    if (typeof raw !== 'string' || !raw.trim() || raw.length > 256) {
+        throw new RunUploadError('manifest_generator_invalid', 'manifest.generator must be a non-empty string of at most 256 characters.');
+    }
+    return raw;
+};
+const assertManifestGraphMatches = (value, graph, graphHash, folderPath) => {
+    if (!isPlainObject(value)) {
+        throw new RunUploadError('manifest_graph_invalid', 'manifest.graph must be an object with nodeCount, edgeCount and graphHash.');
+    }
+    const keys = Object.keys(value).sort().join(',');
+    if (keys !== 'edgeCount,graphHash,nodeCount') {
+        throw new RunUploadError('manifest_graph_invalid', 'manifest.graph must contain exactly nodeCount, edgeCount and graphHash.');
+    }
+    const actual = {
+        nodeCount: graph.nodes.length,
+        edgeCount: graph.edges.length,
+        graphHash,
+    };
+    if (value.nodeCount !== actual.nodeCount ||
+        value.edgeCount !== actual.edgeCount ||
+        value.graphHash !== actual.graphHash) {
+        throw new RunUploadError('folder_corrupt', `This run folder no longer describes itself: its manifest graph counts or hash do not match its own nodes.jsonl / edges.jsonl. ` +
+            `manifest says nodeCount=${String(value.nodeCount)} edgeCount=${String(value.edgeCount)} graphHash=${String(value.graphHash)}; ` +
+            `the files hash to nodeCount=${actual.nodeCount} edgeCount=${actual.edgeCount} graphHash=${actual.graphHash}. ` +
+            `Nothing was sent. Re-export ${folderPath} instead of editing it by hand.`, { details: { expected: actual } });
+    }
+};
+// ---------------------------------------------------------------------------
+// blobs
+// ---------------------------------------------------------------------------
+/** Port of `_reference_only_blob`: keeps only the fields the wire form allows,
+ *  which is also what drops the folder-only `file` path. */
+const referenceOnlyBlob = (raw, index) => {
+    const key = raw.key;
+    if (typeof key !== 'string' || !GRAPH_HASH_RE.test(key)) {
+        throw new RunUploadError('blob_key_invalid', `manifest.blobs[${index}].key must be a lowercase sha256: digest (got ${JSON.stringify(key ?? null)}).`);
+    }
+    const mime = raw.mime;
+    if (typeof mime !== 'string' || !mime.trim() || mime.length > 255) {
+        throw new RunUploadError('blob_mime_invalid', `manifest.blobs[${index}] (${key}) must carry a non-empty mime of at most 255 characters.`);
+    }
+    const size = raw.size;
+    if (typeof size !== 'number' || !Number.isInteger(size) || size < 0) {
+        throw new RunUploadError('blob_size_invalid', `manifest.blobs[${index}] (${key}) must carry a non-negative integer size.`);
+    }
+    const keyDigest = key.slice('sha256:'.length);
+    const sha = 'sha256' in raw ? raw.sha256 : keyDigest;
+    if (typeof sha !== 'string' || !SHA256_HEX_RE.test(sha) || sha !== keyDigest) {
+        throw new RunUploadError('blob_sha256_mismatch', `manifest.blobs[${index}] declares sha256 ${JSON.stringify(sha ?? null)}, which does not match its content-addressed key ${key}. ` +
+            'The folder is corrupt; re-export the run.');
+    }
+    const out = { key, mime, size, sha256: sha };
+    if ('name' in raw) {
+        if (typeof raw.name !== 'string' || raw.name.length > 512) {
+            throw new RunUploadError('blob_name_invalid', `manifest.blobs[${index}] (${key}) name must be a string of at most 512 characters.`);
+        }
+        out.name = raw.name;
+    }
+    if ('artifactId' in raw) {
+        if (typeof raw.artifactId !== 'string' || !raw.artifactId.trim()) {
+            throw new RunUploadError('blob_artifact_id_invalid', `manifest.blobs[${index}] (${key}) artifactId must be a non-empty string.`);
+        }
+        out.artifactId = raw.artifactId;
+    }
+    if ('metadata' in raw) {
+        if (!isPlainObject(raw.metadata)) {
+            throw new RunUploadError('blob_metadata_invalid', `manifest.blobs[${index}] (${key}) metadata must be an object.`);
+        }
+        out.metadata = raw.metadata;
+    }
+    // Anything else on the folder entry — `file` above all — is deliberately
+    // dropped: the registry rejects a snapshot whose blob entries carry a path.
+    return out;
+};
+const assertBlobSetsAgree = (reachable, declared) => {
+    const reachableKeys = new Set(reachable.map(ref => ref.key));
+    const declaredKeys = new Set(declared.map(ref => ref.key));
+    const missing = [...reachableKeys].filter(key => !declaredKeys.has(key)).sort();
+    const unreferenced = [...declaredKeys].filter(key => !reachableKeys.has(key)).sort();
+    if (missing.length === 0 && unreferenced.length === 0)
+        return;
+    throw new RunUploadError('folder_corrupt', 'This run folder\'s blob table does not match the blobs its graph references, and Production Control requires an exact match. ' +
+        (missing.length > 0
+            ? `${missing.length} referenced blob(s) are absent from manifest.blobs (${missing.slice(0, 5).join(', ')}). `
+            : '') +
+        (unreferenced.length > 0
+            ? `${unreferenced.length} declared blob(s) are unreferenced by the graph (${unreferenced.slice(0, 5).join(', ')}). `
+            : '') +
+        'Nothing was sent. Re-export the run.', { details: { missing, unreferenced } });
+};
+const assertBlobMetadataAgrees = (reachable, declared) => {
+    const byKey = new Map(declared.map(ref => [String(ref.key), ref]));
+    for (const ref of reachable) {
+        const entry = byKey.get(ref.key);
+        if (!entry)
+            continue;
+        for (const field of ['mime', 'size', 'sha256', 'name']) {
+            const value = ref[field];
+            if (value === undefined)
+                continue;
+            if (entry[field] !== value) {
+                throw new RunUploadError('folder_corrupt', `This run folder disagrees with itself about blob ${ref.key}: the graph reference says ${field}=${JSON.stringify(value)} ` +
+                    `but manifest.blobs says ${field}=${JSON.stringify(entry[field] ?? null)}. Production Control rejects that. ` +
+                    'Nothing was sent. Re-export the run.', { details: { key: ref.key, field } });
+            }
+        }
+    }
+};
+const planBlobs = async (declared, folder) => {
+    const blobs = [];
+    const oversize = [];
+    for (const entry of declared) {
+        const blobKey = String(entry.key);
+        const file = folder.blobFiles.get(blobKey);
+        if (!file) {
+            throw new RunUploadError('blob_file_missing', `manifest.blobs declares ${blobKey} but gives no \`file\` for it, so its bytes are not in ${folder.path}. ` +
+                'Nothing was sent. Re-export the run with its blobs.', { details: { blobKey } });
+        }
+        let stats;
+        try {
+            stats = await stat(file);
+        }
+        catch (error) {
+            throw new RunUploadError('blob_file_missing', `Run folder blob file is missing: ${file} (for ${blobKey}). Nothing was sent. Re-export the run with its blobs.`, { cause: error, details: { blobKey } });
+        }
+        const declaredSize = Number(entry.size);
+        if (stats.size !== declaredSize) {
+            throw new RunUploadError('blob_file_size_mismatch', `${file} is ${stats.size} bytes but manifest.blobs says ${declaredSize} for ${blobKey}. ` +
+                'The folder is corrupt; nothing was sent. Re-export the run.', { details: { blobKey, onDisk: stats.size, declared: declaredSize } });
+        }
+        if (stats.size > CONTROL_MAX_BLOB_BYTES)
+            oversize.push({ key: blobKey, size: stats.size });
+        blobs.push({
+            blobKey,
+            sha256: String(entry.sha256),
+            mime: String(entry.mime),
+            name: typeof entry.name === 'string' && entry.name ? entry.name : blobKey,
+            size: stats.size,
+            file,
+        });
+    }
+    if (oversize.length > 0) {
+        throw new RunUploadError('blob_too_large', `${oversize.length} blob(s) in this run are larger than the ${formatBytes(CONTROL_MAX_BLOB_BYTES)} Production Control accepts per blob, ` +
+            `the largest being ${formatBytes(Math.max(...oversize.map(item => item.size)))}. Nothing was sent — this run cannot be uploaded as-is. ` +
+            'Re-export it with downscaled assets, or ask for the per-blob limit to be raised.', { details: { blobKeys: oversize.map(item => item.key), limitBytes: CONTROL_MAX_BLOB_BYTES } });
+    }
+    return blobs;
+};
+// ---------------------------------------------------------------------------
+// misc
+// ---------------------------------------------------------------------------
+const registrationMetadata = (folder, createdAt, generator) => {
+    const metadata = {
+        uploadedBy: 'assethub-cli',
+        runFolder: folder.name,
+        graphFolderCreatedAt: createdAt,
+        generator,
+    };
+    if (isPlainObject(folder.manifest.run))
+        metadata.run = folder.manifest.run;
+    if (isPlainObject(folder.manifest.source))
+        metadata.source = folder.manifest.source;
+    return metadata;
+};
+const normalizeTags = (tags) => [...new Set(tags.map(tag => String(tag ?? '').trim()).filter(Boolean))].sort();
+const rejectUnknownFields = (value, allowed, label) => {
+    const allowedSet = new Set(allowed);
+    const unknown = Object.keys(value)
+        .filter(field => !allowedSet.has(field))
+        .sort();
+    if (unknown.length > 0) {
+        throw new RunUploadError('manifest_unknown_fields', `${label} carries fields the registry snapshot format does not allow: ${unknown.join(', ')}. ` +
+            'Nothing was sent. Re-export the run with a current artifact-graph build.', { details: { fields: unknown } });
+    }
+};
+const assertUnderLimit = (label, bytes, limit) => {
+    if (bytes <= limit)
+        return;
+    throw new RunUploadError('payload_too_large', `This run's ${label} is ${formatBytes(bytes)}, over the ${formatBytes(limit)} the snapshot format allows. Nothing was sent.`, { details: { bytes, limitBytes: limit } });
+};
+const asNonNegativeInteger = (value) => {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0)
+        return undefined;
+    return value;
+};
+const isoNoMs = (date) => `${date.toISOString().slice(0, 19)}Z`;
+export const formatBytes = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KiB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+};

package/dist/runsUpload/canonicalJson.d.ts

@@ -0,0 +1,5 @@
+export declare const canonicalJson: (value: unknown) => string;
+export declare const isPlainObject: (value: unknown) => value is Record<string, unknown>;
+export declare const sha256Hex: (input: string) => string;
+export declare const utf8ByteLength: (input: string) => number;
+//# sourceMappingURL=canonicalJson.d.ts.map

package/dist/runsUpload/canonicalJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonicalJson.d.ts","sourceRoot":"","sources":["../../src/runsUpload/canonicalJson.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,MAI9C,CAAA;AAiFD,eAAO,MAAM,aAAa,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CACR,CAAA;AAEtE,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,KAAG,MACgB,CAAA;AAE1D,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAA0C,CAAA"}

package/dist/runsUpload/canonicalJson.js

@@ -0,0 +1,108 @@
+// Vendored from assethub-ml
+// research/artifact-graph/artifact-graph-js/src/graph/commit-reducer.js
+// (canonicalJson and its private helpers ONLY), via the identical vendoring in
+// apps/frontend/src/feature/artifactGraph/export/canonicalJson.ts.
+//
+// These produce byte-identical output to the artifact-graph Python library's
+// `json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)`
+// — which is what the registry recomputes a pushed snapshot's graphHash with.
+// Any drift here makes every push fail validation with an opaque 400, so do NOT
+// edit without re-running the golden vector in
+// src/__tests__/runsUploadPlan.test.ts.
+//
+// One deliberate divergence from the web copy: `sha256Hex` delegates to
+// node:crypto instead of carrying a hand-rolled SHA-256. The web copy runs in
+// the browser/edge bundle and cannot; the CLI is Node-only, and the digest of
+// the same bytes is the same digest.
+import { createHash } from 'node:crypto';
+export const canonicalJson = (value) => {
+    const out = [];
+    writeCanonicalJson(value, out);
+    return out.join('');
+};
+// Sorted-key JSON with numbers rendered exactly as Python's json.dumps renders
+// the reducer's coerced values, so both runtimes produce byte-identical
+// canonical strings (and therefore graph hashes) for the same graph.
+const writeCanonicalJson = (value, out) => {
+    if (value === null || value === undefined) {
+        out.push('null');
+        return;
+    }
+    const type = typeof value;
+    if (type === 'string') {
+        out.push(JSON.stringify(value));
+        return;
+    }
+    if (type === 'boolean') {
+        out.push(value ? 'true' : 'false');
+        return;
+    }
+    if (type === 'number') {
+        out.push(canonicalNumber(value));
+        return;
+    }
+    if (Array.isArray(value)) {
+        out.push('[');
+        for (let index = 0; index < value.length; index += 1) {
+            if (index > 0)
+                out.push(',');
+            writeCanonicalJson(value[index] === undefined ? null : value[index], out);
+        }
+        out.push(']');
+        return;
+    }
+    if (isPlainObject(value)) {
+        out.push('{');
+        let first = true;
+        for (const key of Object.keys(value).sort()) {
+            const entry = value[key];
+            if (entry === undefined || typeof entry === 'function' || typeof entry === 'symbol')
+                continue;
+            if (!first)
+                out.push(',');
+            first = false;
+            out.push(JSON.stringify(key), ':');
+            writeCanonicalJson(entry, out);
+        }
+        out.push('}');
+        return;
+    }
+    out.push(JSON.stringify(value) ?? 'null');
+};
+const canonicalNumber = (value) => {
+    if (!Number.isFinite(value))
+        return 'null';
+    // Integral doubles below 2^53 print as plain digits, matching the Python
+    // reducer, which coerces exactly that range to int at ingestion. Above
+    // 2^53 exact-integer digits and shortest-digit rendering diverge, so those
+    // take the float path on both sides.
+    if (Number.isInteger(value) && Math.abs(value) < 9007199254740992)
+        return String(value);
+    return pythonFloatRepr(value);
+};
+// CPython float repr for a finite double: shortest round-trip digits, fixed
+// notation while -4 < decpt <= 16 (with a trailing ".0" for integral values),
+// otherwise scientific with a signed, zero-padded-to-two-digits exponent
+// (1e-05, 1.5e+22). The shortest-digit sequence itself is identical in both
+// runtimes; only the placement rules differ from ECMAScript's String(x).
+const pythonFloatRepr = (value) => {
+    const exponential = value.toExponential();
+    const [mantissa, exponentRaw] = exponential.split('e');
+    const sign = mantissa.startsWith('-') ? '-' : '';
+    const digits = mantissa.replace('-', '').replace('.', '');
+    const decpt = Number(exponentRaw) + 1;
+    if (decpt > -4 && decpt <= 16) {
+        if (decpt <= 0)
+            return `${sign}0.${'0'.repeat(-decpt)}${digits}`;
+        if (decpt >= digits.length)
+            return `${sign}${digits}${'0'.repeat(decpt - digits.length)}.0`;
+        return `${sign}${digits.slice(0, decpt)}.${digits.slice(decpt)}`;
+    }
+    const exponent = decpt - 1;
+    const exponentDigits = String(Math.abs(exponent)).padStart(2, '0');
+    const fraction = digits.length > 1 ? `.${digits.slice(1)}` : '';
+    return `${sign}${digits[0]}${fraction}e${exponent < 0 ? '-' : '+'}${exponentDigits}`;
+};
+export const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+export const sha256Hex = (input) => createHash('sha256').update(input, 'utf8').digest('hex');
+export const utf8ByteLength = (input) => Buffer.byteLength(input, 'utf8');

package/dist/runsUpload/controlEndpoints.d.ts

@@ -0,0 +1,63 @@
+/**
+ * THE ONE PLACE the Production Control run-upload wire contract lives.
+ *
+ * The backend for these routes is being built in parallel. Everything the CLI
+ * knows about *where* to send bytes and *how big* they may be is in this file,
+ * so a late change on the server side is a one-line edit here rather than a
+ * sweep through the transport.
+ *
+ * Route shape mirrors the Cloudflare ag-registry Worker
+ * (assethub-ml research/artifact-graph/cloud/registry-worker/src/worker.js)
+ * because the payloads are the same `ag.registry.v1` documents. Only the prefix
+ * and the transport envelope differ: these live on AssetHub's public v2 API
+ * surface, behind `withExposedApi()` + API-key auth, so they speak AssetHub's
+ * `{success, data}` / `{success, error}` envelope rather than
+ * `ag.registry-error.v1`.
+ */
+/** Change this one line if the backend lands on a different prefix. */
+export declare const CONTROL_RUN_UPLOAD_API_PREFIX = "/api/v2/production/run-uploads";
+export type ControlRunUploadUrls = {
+    /** POST — register the graph. Required before any blob or snapshot lands. */
+    graphs: string;
+    /** PUT — the `ag.registry-push.v1` envelope. */
+    snapshot: (graphId: string) => string;
+    /** HEAD (does the pool already hold these bytes?) / PUT (send them). */
+    blob: (graphId: string, blobKey: string) => string;
+};
+export declare const controlRunUploadUrls: (baseUrl: string) => ControlRunUploadUrls;
+/**
+ * Server-enforced ceilings, checked locally so a doomed run is rejected before
+ * the first byte leaves rather than after N blobs have already landed.
+ *
+ * The `ag.registry.v1` format allows far more (64 MiB graph arrays, 2 MiB
+ * manifest). These smaller numbers are the real ceiling: the routes run on
+ * Vercel Serverless, whose request-body limit bites first.
+ */
+export declare const CONTROL_MAX_BLOB_BYTES: number;
+export declare const CONTROL_MAX_PUSH_BYTES: number;
+/** Format-level ceilings from the registry contract, checked for completeness. */
+export declare const REGISTRY_MAX_MANIFEST_BYTES: number;
+export declare const REGISTRY_MAX_GRAPH_ARRAY_BYTES: number;
+export declare const REGISTRY_MAX_METADATA_BYTES: number;
+/**
+ * Error codes the routes answer with. Values follow AssetHub's public-API
+ * SCREAMING_SNAKE convention; the semantics follow the registry's.
+ */
+export declare const CONTROL_ERROR_CODES: {
+    /** 409 — the snapshot references bytes the pool does not hold yet. */
+    readonly missingBlobs: "MISSING_BLOBS";
+    /** 409 — same rev, different graphHash. A genuine divergence. */
+    readonly snapshotConflict: "SNAPSHOT_CONFLICT";
+    /** 409 — the server already holds a newer rev. Desired end state, not a failure. */
+    readonly staleSnapshot: "STALE_SNAPSHOT";
+    readonly payloadTooLarge: "PAYLOAD_TOO_LARGE";
+    /** 404 — the graph was never registered by this org. Distinct from "no access". */
+    readonly notRegistered: "NOT_REGISTERED";
+};
+/**
+ * These routes are internal-only. An API key whose owner is not an internal
+ * user, or whose org lacks the Production Control entitlement, gets 404 rather
+ * than 403 — the path's existence is itself not disclosed.
+ */
+export declare const CONTROL_NOT_ENTITLED_STATUS = 404;
+//# sourceMappingURL=controlEndpoints.d.ts.map

package/dist/runsUpload/controlEndpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlEndpoints.d.ts","sourceRoot":"","sources":["../../src/runsUpload/controlEndpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,uEAAuE;AACvE,eAAO,MAAM,6BAA6B,mCAAmC,CAAA;AAI7E,MAAM,MAAM,oBAAoB,GAAG;IACjC,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAA;IACd,gDAAgD;IAChD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACrC,wEAAwE;IACxE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;CACnD,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,SAAS,MAAM,KAAG,oBAUtD,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,QAAkB,CAAA;AACrD,eAAO,MAAM,sBAAsB,QAAkB,CAAA;AAErD,kFAAkF;AAClF,eAAO,MAAM,2BAA2B,QAAkB,CAAA;AAC1D,eAAO,MAAM,8BAA8B,QAAmB,CAAA;AAC9D,eAAO,MAAM,2BAA2B,QAAa,CAAA;AAErD;;;GAGG;AACH,eAAO,MAAM,mBAAmB;IAC9B,sEAAsE;;IAEtE,iEAAiE;;IAEjE,oFAAoF;;;IAGpF,mFAAmF;;CAE3E,CAAA;AAEV;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAA"}