@obversa/api 0.1.0

package/dist/chunk-WGLWWKF3.js

@@ -0,0 +1,135 @@
+import { StorageError } from './chunk-AJ353QD5.js';
+import { Buffer } from 'buffer';
+
+// src/storage/id.ts
+var SAFE_STORAGE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+function validateStorageId(value, path) {
+  if (typeof value !== "string" || !SAFE_STORAGE_ID.test(value)) {
+    throw new StorageError(
+      "INVALID_STORED_VALUE",
+      "Storage id must contain 1 to 128 ASCII characters, start with a letter or digit, and otherwise use only letters, digits, dots, underscores, or hyphens.",
+      { path }
+    );
+  }
+  return value;
+}
+var DIGEST = /^sha256:[0-9a-f]{64}$/u;
+var MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/iu;
+var CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/u;
+var CONTENT_MODES = /* @__PURE__ */ new Set(["exact", "state", "free-text"]);
+function fail(path, message) {
+  throw new StorageError("INVALID_STORED_VALUE", message, { path });
+}
+function record(value, path, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    fail(path, `${label} must be an object.`);
+  }
+  return value;
+}
+function exactFields(value, required, optional, path) {
+  for (const field of required) {
+    if (!Object.hasOwn(value, field)) {
+      fail(`${path}/${field}`, `Required field "${field}" is missing.`);
+    }
+  }
+  const allowed = /* @__PURE__ */ new Set([...required, ...optional]);
+  for (const field of Object.keys(value)) {
+    if (!allowed.has(field)) {
+      fail(`${path}/${field}`, `Unknown field "${field}" is not allowed.`);
+    }
+  }
+}
+function text(value, path, label) {
+  if (typeof value !== "string" || value.length === 0 || value !== value.trim() || CONTROL_CHARACTER.test(value)) {
+    fail(path, `${label} must be a non-empty trimmed string without control characters.`);
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const unit = value.charCodeAt(index);
+    if (unit >= 55296 && unit <= 56319) {
+      const next = value.charCodeAt(index + 1);
+      if (!Number.isInteger(next) || next < 56320 || next > 57343) {
+        fail(path, `${label} must contain valid Unicode.`);
+      }
+      index += 1;
+      continue;
+    }
+    if (unit >= 56320 && unit <= 57343) {
+      fail(path, `${label} must contain valid Unicode.`);
+    }
+  }
+  return value;
+}
+function boundedText(value, path, label, maxBytes) {
+  const result = text(value, path, label);
+  if (Buffer.byteLength(result, "utf8") > maxBytes) {
+    fail(path, `${label} must not exceed ${maxBytes} UTF-8 bytes.`);
+  }
+  return result;
+}
+function mediaType(value, path) {
+  const result = boundedText(value, path, "Media type", 255);
+  if (!MEDIA_TYPE.test(result)) fail(path, "Media type must be a type/subtype value.");
+  return result;
+}
+function validateArtifactScope(value) {
+  const item = record(value, "", "Artifact scope");
+  exactFields(item, ["namespace", "runId"], [], "");
+  return Object.freeze({
+    namespace: validateStorageId(item.namespace, "/namespace"),
+    runId: validateStorageId(item.runId, "/runId")
+  });
+}
+function validateNewArtifact(value) {
+  const item = record(value, "", "New artifact");
+  exactFields(
+    item,
+    ["bytes", "mediaType", "purpose", "contentMode"],
+    ["sensitive"],
+    ""
+  );
+  if (!(item.bytes instanceof Uint8Array)) {
+    fail("/bytes", "Artifact bytes must be a Uint8Array.");
+  }
+  if (!CONTENT_MODES.has(item.contentMode)) {
+    fail("/contentMode", "Content mode must be exact, state, or free-text.");
+  }
+  if (item.sensitive !== void 0 && typeof item.sensitive !== "boolean") {
+    fail("/sensitive", "Sensitive must be a boolean when supplied.");
+  }
+  return Object.freeze({
+    bytes: Uint8Array.from(item.bytes),
+    mediaType: mediaType(item.mediaType, "/mediaType"),
+    purpose: boundedText(item.purpose, "/purpose", "Purpose", 512),
+    contentMode: item.contentMode,
+    ...item.sensitive === void 0 ? {} : { sensitive: item.sensitive }
+  });
+}
+function validateArtifactReference(value) {
+  const item = record(value, "", "Artifact reference");
+  exactFields(
+    item,
+    ["schemaVersion", "digest", "byteLength", "mediaType", "purpose"],
+    [],
+    ""
+  );
+  if (item.schemaVersion !== 1) {
+    fail("/schemaVersion", "Artifact reference schemaVersion must be 1.");
+  }
+  if (typeof item.digest !== "string" || !DIGEST.test(item.digest)) {
+    fail("/digest", "Digest must be lowercase sha256 followed by 64 hexadecimal characters.");
+  }
+  if (!Number.isSafeInteger(item.byteLength) || item.byteLength < 0) {
+    fail("/byteLength", "Byte length must be a non-negative safe integer.");
+  }
+  return Object.freeze({
+    schemaVersion: 1,
+    digest: item.digest,
+    byteLength: item.byteLength,
+    mediaType: mediaType(item.mediaType, "/mediaType"),
+    purpose: boundedText(item.purpose, "/purpose", "Purpose", 512)
+  });
+}
+
+export { validateArtifactReference, validateArtifactScope, validateNewArtifact, validateStorageId };
+//# sourceMappingURL=chunk-WGLWWKF3.js.map
+//# sourceMappingURL=chunk-WGLWWKF3.js.map

package/dist/chunk-WGLWWKF3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage/id.ts","../src/artifacts/store.ts"],"names":[],"mappings":";;;;AAEA,IAAM,eAAA,GAAkB,qCAAA;AAGjB,SAAS,iBAAA,CAAkB,OAAgB,IAAA,EAAsB;AACtE,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,IAAY,CAAC,eAAA,CAAgB,IAAA,CAAK,KAAK,CAAA,EAAG;AAC7D,IAAA,MAAM,IAAI,YAAA;AAAA,MACR,sBAAA;AAAA,MACA,yJAAA;AAAA,MACA,EAAE,IAAA;AAAK,KACT;AAAA,EACF;AACA,EAAA,OAAO,KAAA;AACT;AC2BA,IAAM,MAAA,GAAS,wBAAA;AACf,IAAM,UAAA,GAAa,4DAAA;AACnB,IAAM,iBAAA,GAAoB,wBAAA;AAC1B,IAAM,gCAAgB,IAAI,GAAA,CAAyB,CAAC,OAAA,EAAS,OAAA,EAAS,WAAW,CAAC,CAAA;AAElF,SAAS,IAAA,CAAK,MAAc,OAAA,EAAwB;AAClD,EAAA,MAAM,IAAI,YAAA,CAAa,sBAAA,EAAwB,OAAA,EAAS,EAAE,MAAM,CAAA;AAClE;AAEA,SAAS,MAAA,CAAO,KAAA,EAAgB,IAAA,EAAc,KAAA,EAAwC;AACpF,EAAA,IAAI,KAAA,KAAU,QAAQ,OAAO,KAAA,KAAU,YAAY,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA,EAAG;AACvE,IAAA,IAAA,CAAK,IAAA,EAAM,CAAA,EAAG,KAAK,CAAA,mBAAA,CAAqB,CAAA;AAAA,EAC1C;AACA,EAAA,OAAO,KAAA;AACT;AAEA,SAAS,WAAA,CACP,KAAA,EACA,QAAA,EACA,QAAA,EACA,IAAA,EACM;AACN,EAAA,KAAA,MAAW,SAAS,QAAA,EAAU;AAC5B,IAAA,IAAI,CAAC,MAAA,CAAO,MAAA,CAAO,KAAA,EAAO,KAAK,CAAA,EAAG;AAChC,MAAA,IAAA,CAAK,GAAG,IAAI,CAAA,CAAA,EAAI,KAAK,CAAA,CAAA,EAAI,CAAA,gBAAA,EAAmB,KAAK,CAAA,aAAA,CAAe,CAAA;AAAA,IAClE;AAAA,EACF;AACA,EAAA,MAAM,OAAA,uBAAc,GAAA,CAAI,CAAC,GAAG,QAAA,EAAU,GAAG,QAAQ,CAAC,CAAA;AAClD,EAAA,KAAA,MAAW,KAAA,IAAS,MAAA,CAAO,IAAA,CAAK,KAAK,CAAA,EAAG;AACtC,IAAA,IAAI,CAAC,OAAA,CAAQ,GAAA,CAAI,KAAK,CAAA,EAAG;AACvB,MAAA,IAAA,CAAK,GAAG,IAAI,CAAA,CAAA,EAAI,KAAK,CAAA,CAAA,EAAI,CAAA,eAAA,EAAkB,KAAK,CAAA,iBAAA,CAAmB,CAAA;AAAA,IACrE;AAAA,EACF;AACF;AAEA,SAAS,IAAA,CAAK,KAAA,EAAgB,IAAA,EAAc,KAAA,EAAuB;AACjE,EAAA,IACE,OAAO,KAAA,KAAU,QAAA,IACd,KAAA,CAAM,MAAA,KAAW,CAAA,IACjB,KAAA,KAAU,KAAA,CAAM,IAAA,EAAK,IACrB,iBAAA,CAAkB,IAAA,CAAK,KAAK,CAAA,EAC/B;AACA,IAAA,IAAA,CAAK,IAAA,EAAM,CAAA,EAAG,KAAK,CAAA,+DAAA,CAAiE,CAAA;AAAA,EACtF;AACA,EAAA,KAAA,IAAS,QAAQ,CAAA,EAAG,KAAA,GAAQ,KAAA,CAAM,MAAA,EAAQ,SAAS,CAAA,EAAG;AACpD,IAAA,MAAM,IAAA,GAAO,KAAA,CAAM,UAAA,CAAW,KAAK,CAAA;AACnC,IAAA,IAAI,IAAA,IAAQ,KAAA,IAAU,IAAA,IAAQ,KAAA,EAAQ;AACpC,MAAA,MAAM,IAAA,GAAO,KAAA,CAAM,UAAA,CAAW,KAAA,GAAQ,CAAC,CAAA;AACvC,MAAA,IAAI,CAAC,OAAO,SAAA,CAAU,IAAI,KAAK,IAAA,GAAO,KAAA,IAAU,OAAO,KAAA,EAAQ;AAC7D,QAAA,IAAA,CAAK,IAAA,EAAM,CAAA,EAAG,KAAK,CAAA,4BAAA,CAA8B,CAAA;AAAA,MACnD;AACA,MAAA,KAAA,IAAS,CAAA;AACT,MAAA;AAAA,IACF;AACA,IAAA,IAAI,IAAA,IAAQ,KAAA,IAAU,IAAA,IAAQ,KAAA,EAAQ;AACpC,MAAA,IAAA,CAAK,IAAA,EAAM,CAAA,EAAG,KAAK,CAAA,4BAAA,CAA8B,CAAA;AAAA,IACnD;AAAA,EACF;AACA,EAAA,OAAO,KAAA;AACT;AAEA,SAAS,WAAA,CACP,KAAA,EACA,IAAA,EACA,KAAA,EACA,QAAA,EACQ;AACR,EAAA,MAAM,MAAA,GAAS,IAAA,CAAK,KAAA,EAAO,IAAA,EAAM,KAAK,CAAA;AACtC,EAAA,IAAI,MAAA,CAAO,UAAA,CAAW,MAAA,EAAQ,MAAM,IAAI,QAAA,EAAU;AAChD,IAAA,IAAA,CAAK,IAAA,EAAM,CAAA,EAAG,KAAK,CAAA,iBAAA,EAAoB,QAAQ,CAAA,aAAA,CAAe,CAAA;AAAA,EAChE;AACA,EAAA,OAAO,MAAA;AACT;AAEA,SAAS,SAAA,CAAU,OAAgB,IAAA,EAAsB;AACvD,EAAA,MAAM,MAAA,GAAS,WAAA,CAAY,KAAA,EAAO,IAAA,EAAM,cAAc,GAAG,CAAA;AACzD,EAAA,IAAI,CAAC,UAAA,CAAW,IAAA,CAAK,MAAM,CAAA,EAAG,IAAA,CAAK,MAAM,0CAA0C,CAAA;AACnF,EAAA,OAAO,MAAA;AACT;AAEO,SAAS,sBAAsB,KAAA,EAA+B;AACnE,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,KAAA,EAAO,EAAA,EAAI,gBAAgB,CAAA;AAC/C,EAAA,WAAA,CAAY,MAAM,CAAC,WAAA,EAAa,OAAO,CAAA,EAAG,IAAI,EAAE,CAAA;AAChD,EAAA,OAAO,OAAO,MAAA,CAAO;AAAA,IACnB,SAAA,EAAW,iBAAA,CAAkB,IAAA,CAAK,SAAA,EAAW,YAAY,CAAA;AAAA,IACzD,KAAA,EAAO,iBAAA,CAAkB,IAAA,CAAK,KAAA,EAAO,QAAQ;AAAA,GAC9C,CAAA;AACH;AAEO,SAAS,oBAAoB,KAAA,EAA6B;AAC/D,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,KAAA,EAAO,EAAA,EAAI,cAAc,CAAA;AAC7C,EAAA,WAAA;AAAA,IACE,IAAA;AAAA,IACA,CAAC,OAAA,EAAS,WAAA,EAAa,SAAA,EAAW,aAAa,CAAA;AAAA,IAC/C,CAAC,WAAW,CAAA;AAAA,IACZ;AAAA,GACF;AACA,EAAA,IAAI,EAAE,IAAA,CAAK,KAAA,YAAiB,UAAA,CAAA,EAAa;AACvC,IAAA,IAAA,CAAK,UAAU,sCAAsC,CAAA;AAAA,EACvD;AACA,EAAA,IAAI,CAAC,aAAA,CAAc,GAAA,CAAI,IAAA,CAAK,WAAkC,CAAA,EAAG;AAC/D,IAAA,IAAA,CAAK,gBAAgB,kDAAkD,CAAA;AAAA,EACzE;AACA,EAAA,IAAI,KAAK,SAAA,KAAc,MAAA,IAAa,OAAO,IAAA,CAAK,cAAc,SAAA,EAAW;AACvE,IAAA,IAAA,CAAK,cAAc,4CAA4C,CAAA;AAAA,EACjE;AAEA,EAAA,OAAO,OAAO,MAAA,CAAO;AAAA,IACnB,KAAA,EAAO,UAAA,CAAW,IAAA,CAAK,IAAA,CAAK,KAAK,CAAA;AAAA,IACjC,SAAA,EAAW,SAAA,CAAU,IAAA,CAAK,SAAA,EAAW,YAAY,CAAA;AAAA,IACjD,SAAS,WAAA,CAAY,IAAA,CAAK,OAAA,EAAS,UAAA,EAAY,WAAW,GAAG,CAAA;AAAA,IAC7D,aAAa,IAAA,CAAK,WAAA;AAAA,IAClB,GAAI,KAAK,SAAA,KAAc,MAAA,GAAY,EAAC,GAAI,EAAE,SAAA,EAAW,IAAA,CAAK,SAAA;AAAU,GACrE,CAAA;AACH;AAEO,SAAS,0BAA0B,KAAA,EAAmC;AAC3E,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,KAAA,EAAO,EAAA,EAAI,oBAAoB,CAAA;AACnD,EAAA,WAAA;AAAA,IACE,IAAA;AAAA,IACA,CAAC,eAAA,EAAiB,QAAA,EAAU,YAAA,EAAc,aAAa,SAAS,CAAA;AAAA,IAChE,EAAC;AAAA,IACD;AAAA,GACF;AACA,EAAA,IAAI,IAAA,CAAK,kBAAkB,CAAA,EAAG;AAC5B,IAAA,IAAA,CAAK,kBAAkB,6CAA6C,CAAA;AAAA,EACtE;AACA,EAAA,IAAI,OAAO,KAAK,MAAA,KAAW,QAAA,IAAY,CAAC,MAAA,CAAO,IAAA,CAAK,IAAA,CAAK,MAAM,CAAA,EAAG;AAChE,IAAA,IAAA,CAAK,WAAW,wEAAwE,CAAA;AAAA,EAC1F;AACA,EAAA,IAAI,CAAC,OAAO,aAAA,CAAc,IAAA,CAAK,UAAU,CAAA,IAAM,IAAA,CAAK,aAAwB,CAAA,EAAG;AAC7E,IAAA,IAAA,CAAK,eAAe,kDAAkD,CAAA;AAAA,EACxE;AAEA,EAAA,OAAO,OAAO,MAAA,CAAO;AAAA,IACnB,aAAA,EAAe,CAAA;AAAA,IACf,QAAQ,IAAA,CAAK,MAAA;AAAA,IACb,YAAY,IAAA,CAAK,UAAA;AAAA,IACjB,SAAA,EAAW,SAAA,CAAU,IAAA,CAAK,SAAA,EAAW,YAAY,CAAA;AAAA,IACjD,SAAS,WAAA,CAAY,IAAA,CAAK,OAAA,EAAS,UAAA,EAAY,WAAW,GAAG;AAAA,GAC9D,CAAA;AACH","file":"chunk-WGLWWKF3.js","sourcesContent":["import { StorageError } from './error.js';\n\nconst SAFE_STORAGE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;\n\n/** Validate one namespace, stream, or run identity used by a storage port. */\nexport function validateStorageId(value: unknown, path: string): string {\n  if (typeof value !== 'string' || !SAFE_STORAGE_ID.test(value)) {\n    throw new StorageError(\n      'INVALID_STORED_VALUE',\n      'Storage id must contain 1 to 128 ASCII characters, start with a letter or digit, and otherwise use only letters, digits, dots, underscores, or hyphens.',\n      { path },\n    );\n  }\n  return value;\n}\n","import { Buffer } from 'node:buffer';\n\nimport { StorageError } from '../storage/error.js';\nimport { validateStorageId } from '../storage/id.js';\nimport type { JsonObject, Sha256Digest } from '../json.js';\n\nexport type ArtifactContentMode = 'exact' | 'state' | 'free-text';\n\nexport interface ArtifactScope {\n  readonly namespace: string;\n  readonly runId: string;\n}\n\nexport interface NewArtifact {\n  readonly bytes: Uint8Array;\n  readonly mediaType: string;\n  readonly purpose: string;\n  readonly contentMode: ArtifactContentMode;\n  readonly sensitive?: boolean;\n}\n\nexport type ArtifactBatch = readonly [NewArtifact, ...NewArtifact[]];\n\nexport interface ArtifactReference<Purpose extends string = string> extends JsonObject {\n  readonly schemaVersion: 1;\n  readonly digest: Sha256Digest;\n  readonly byteLength: number;\n  readonly mediaType: string;\n  readonly purpose: Purpose;\n}\n\nexport interface ArtifactStore {\n  preflightWrite(\n    scope: ArtifactScope,\n    artifacts: ArtifactBatch,\n  ): Promise<readonly ArtifactReference[]>;\n  write(scope: ArtifactScope, artifact: NewArtifact): Promise<ArtifactReference>;\n  read(scope: ArtifactScope, reference: ArtifactReference): Promise<Uint8Array>;\n  deleteRun(scope: ArtifactScope): Promise<void>;\n}\n\nconst DIGEST = /^sha256:[0-9a-f]{64}$/u;\nconst MEDIA_TYPE = /^[a-z0-9][a-z0-9!#$&^_.+-]*\\/[a-z0-9][a-z0-9!#$&^_.+-]*$/iu;\nconst CONTROL_CHARACTER = /[\\u0000-\\u001f\\u007f]/u;\nconst CONTENT_MODES = new Set<ArtifactContentMode>(['exact', 'state', 'free-text']);\n\nfunction fail(path: string, message: string): never {\n  throw new StorageError('INVALID_STORED_VALUE', message, { path });\n}\n\nfunction record(value: unknown, path: string, label: string): Record<string, unknown> {\n  if (value === null || typeof value !== 'object' || Array.isArray(value)) {\n    fail(path, `${label} must be an object.`);\n  }\n  return value as Record<string, unknown>;\n}\n\nfunction exactFields(\n  value: Record<string, unknown>,\n  required: readonly string[],\n  optional: readonly string[],\n  path: string,\n): void {\n  for (const field of required) {\n    if (!Object.hasOwn(value, field)) {\n      fail(`${path}/${field}`, `Required field \"${field}\" is missing.`);\n    }\n  }\n  const allowed = new Set([...required, ...optional]);\n  for (const field of Object.keys(value)) {\n    if (!allowed.has(field)) {\n      fail(`${path}/${field}`, `Unknown field \"${field}\" is not allowed.`);\n    }\n  }\n}\n\nfunction text(value: unknown, path: string, label: string): string {\n  if (\n    typeof value !== 'string'\n    || value.length === 0\n    || value !== value.trim()\n    || CONTROL_CHARACTER.test(value)\n  ) {\n    fail(path, `${label} must be a non-empty trimmed string without control characters.`);\n  }\n  for (let index = 0; index < value.length; index += 1) {\n    const unit = value.charCodeAt(index);\n    if (unit >= 0xd800 && unit <= 0xdbff) {\n      const next = value.charCodeAt(index + 1);\n      if (!Number.isInteger(next) || next < 0xdc00 || next > 0xdfff) {\n        fail(path, `${label} must contain valid Unicode.`);\n      }\n      index += 1;\n      continue;\n    }\n    if (unit >= 0xdc00 && unit <= 0xdfff) {\n      fail(path, `${label} must contain valid Unicode.`);\n    }\n  }\n  return value;\n}\n\nfunction boundedText(\n  value: unknown,\n  path: string,\n  label: string,\n  maxBytes: number,\n): string {\n  const result = text(value, path, label);\n  if (Buffer.byteLength(result, 'utf8') > maxBytes) {\n    fail(path, `${label} must not exceed ${maxBytes} UTF-8 bytes.`);\n  }\n  return result;\n}\n\nfunction mediaType(value: unknown, path: string): string {\n  const result = boundedText(value, path, 'Media type', 255);\n  if (!MEDIA_TYPE.test(result)) fail(path, 'Media type must be a type/subtype value.');\n  return result;\n}\n\nexport function validateArtifactScope(value: unknown): ArtifactScope {\n  const item = record(value, '', 'Artifact scope');\n  exactFields(item, ['namespace', 'runId'], [], '');\n  return Object.freeze({\n    namespace: validateStorageId(item.namespace, '/namespace'),\n    runId: validateStorageId(item.runId, '/runId'),\n  });\n}\n\nexport function validateNewArtifact(value: unknown): NewArtifact {\n  const item = record(value, '', 'New artifact');\n  exactFields(\n    item,\n    ['bytes', 'mediaType', 'purpose', 'contentMode'],\n    ['sensitive'],\n    '',\n  );\n  if (!(item.bytes instanceof Uint8Array)) {\n    fail('/bytes', 'Artifact bytes must be a Uint8Array.');\n  }\n  if (!CONTENT_MODES.has(item.contentMode as ArtifactContentMode)) {\n    fail('/contentMode', 'Content mode must be exact, state, or free-text.');\n  }\n  if (item.sensitive !== undefined && typeof item.sensitive !== 'boolean') {\n    fail('/sensitive', 'Sensitive must be a boolean when supplied.');\n  }\n\n  return Object.freeze({\n    bytes: Uint8Array.from(item.bytes),\n    mediaType: mediaType(item.mediaType, '/mediaType'),\n    purpose: boundedText(item.purpose, '/purpose', 'Purpose', 512),\n    contentMode: item.contentMode as ArtifactContentMode,\n    ...(item.sensitive === undefined ? {} : { sensitive: item.sensitive }),\n  });\n}\n\nexport function validateArtifactReference(value: unknown): ArtifactReference {\n  const item = record(value, '', 'Artifact reference');\n  exactFields(\n    item,\n    ['schemaVersion', 'digest', 'byteLength', 'mediaType', 'purpose'],\n    [],\n    '',\n  );\n  if (item.schemaVersion !== 1) {\n    fail('/schemaVersion', 'Artifact reference schemaVersion must be 1.');\n  }\n  if (typeof item.digest !== 'string' || !DIGEST.test(item.digest)) {\n    fail('/digest', 'Digest must be lowercase sha256 followed by 64 hexadecimal characters.');\n  }\n  if (!Number.isSafeInteger(item.byteLength) || (item.byteLength as number) < 0) {\n    fail('/byteLength', 'Byte length must be a non-negative safe integer.');\n  }\n\n  return Object.freeze({\n    schemaVersion: 1,\n    digest: item.digest as Sha256Digest,\n    byteLength: item.byteLength as number,\n    mediaType: mediaType(item.mediaType, '/mediaType'),\n    purpose: boundedText(item.purpose, '/purpose', 'Purpose', 512),\n  });\n}\n"]}

package/dist/contracts.d.ts

@@ -0,0 +1,122 @@
+/** Provider-neutral values and behavior shared by runtimes and engine plugins. */
+import type { JsonValue } from './json.js';
+export type { JsonObject, JsonPrimitive, JsonValue, Sha256Digest, } from './json.js';
+export { JsonValueError, canonicalJson, cloneFrozenJson, digestJson, } from './json.js';
+export interface AttemptMetadata {
+    leaf: boolean;
+    runId?: string;
+    attemptId?: string;
+    leafId: string;
+    path: string[];
+    label: string;
+    iteration: number;
+}
+export interface Usage {
+    /** Total input, including cache creation and cache reads where reported. */
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+}
+export type UsageReceipt = {
+    readonly kind: 'unknown';
+} | ({
+    readonly kind: 'reported';
+} & Usage);
+export type AgentResultPart = {
+    readonly kind: 'assistant';
+    readonly text: string;
+    readonly final: boolean;
+} | {
+    readonly kind: 'structured';
+    readonly value: JsonValue;
+    readonly final: true;
+};
+export interface EngineSelectionRecord {
+    readonly adapter: string;
+    readonly adapterVersion: string | null;
+    readonly provider: string | null;
+    readonly modelFamily: string | null;
+    readonly model: string | null;
+    readonly executable: string | null;
+    readonly capabilities: readonly string[];
+}
+export interface ExecutionTarget {
+    readonly adapter: string;
+    readonly provider: string;
+    readonly modelFamily: string;
+    readonly model: string;
+    readonly tools: readonly string[];
+}
+export interface TeamSeat {
+    readonly engine: Engine;
+    readonly identity: ExecutionTarget;
+}
+export type EngineFailureKind = 'auth' | 'billing' | 'missing-cli' | 'model-unavailable' | 'invalid-config' | 'rate-limit' | 'quota' | 'transient' | 'timeout' | 'aborted' | 'unknown';
+export interface EngineTransportFailure {
+    readonly kind: EngineFailureKind;
+    readonly message: string;
+    readonly exitCode: number | null;
+}
+/** Tools used by supported agent hosts to dispatch sub-agents. */
+export declare const SUBAGENT_TOOLS: string[];
+export declare const CLAUDE_SUBAGENT_TOOLS: string[];
+export interface AgentRequest {
+    prompt: string;
+    purpose?: 'preflight';
+    system?: string;
+    systemMode?: 'append' | 'replace';
+    model?: string;
+    maxTokens?: number;
+    jsonSchema?: JsonValue;
+    tools?: string[];
+    allowedTools?: string[];
+    workspaceMode?: 'none' | 'read' | 'write';
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    timeoutGraceMs?: number;
+    maxOutputBytes?: number;
+    maxMemoryBytes?: number;
+    attempt?: AttemptMetadata;
+    leaf?: boolean;
+}
+/** A read-only workspace must expose at least one tool that can read it. */
+export declare function assertReadAccess(request: Pick<AgentRequest, 'tools' | 'workspaceMode'>): void;
+export interface AgentResult {
+    /** Ordered assistant continuations with exactly one marked final part. */
+    readonly parts: readonly AgentResultPart[];
+    readonly usage: UsageReceipt;
+    readonly requested: EngineSelectionRecord;
+    readonly effective: EngineSelectionRecord;
+    readonly stopReason?: string;
+    readonly transportFailure?: EngineTransportFailure;
+    readonly raw?: unknown;
+}
+export type EngineIncompleteResultEvidence = Omit<AgentResult, 'parts'> & {
+    readonly parts: readonly AgentResultPart[];
+};
+export type EngineStreamEvent = {
+    type: 'text';
+    delta: string;
+} | {
+    type: 'thinking';
+    delta: string;
+} | {
+    type: 'tool';
+    name: string;
+    phase: 'use' | 'result';
+} | {
+    type: 'usage';
+    usage: UsageReceipt;
+    model: string;
+};
+export type EngineEventSink = (event: EngineStreamEvent) => void;
+export interface Engine {
+    readonly name: string;
+    admit?(request: Omit<AgentRequest, 'prompt'>, signal: AbortSignal, expectedSelection?: EngineSelectionRecord): Promise<EngineSelectionRecord>;
+    run(request: AgentRequest, onEvent: EngineEventSink, signal: AbortSignal): Promise<AgentResult>;
+}
+export type EngineRef = string | Engine;
+export type EngineName = string;
+export declare function isEngine(value: unknown): value is Engine;

package/dist/engine-conformance.d.ts

@@ -0,0 +1,80 @@
+import type { AgentRequest, AgentResultPart, Engine, EngineSelectionRecord } from './contracts.js';
+import type { JsonValue } from './json.js';
+export type EngineConformanceScenario = 'ordered-parts' | 'structured-result' | 'unknown-usage' | 'reported-usage' | 'tool-events' | 'late-final' | 'cancellation' | 'missing-cli' | 'auth' | 'billing' | 'model-unavailable' | 'rate-limit' | 'quota' | 'transient' | 'timeout' | 'invalid-config' | 'read-access' | 'workspace-none' | 'workspace-read' | 'workspace-write';
+type WorkspaceMode = NonNullable<AgentRequest['workspaceMode']>;
+type FeatureScenario = Exclude<EngineConformanceScenario, 'read-access' | `workspace-${WorkspaceMode}`>;
+export interface EngineConformanceFixture {
+    readonly request: AgentRequest;
+    readonly requested: EngineSelectionRecord;
+    readonly effective: EngineSelectionRecord;
+    readonly unsupported?: Partial<Record<FeatureScenario, string>>;
+    readonly workspace: {
+        readonly modes: Record<WorkspaceMode, {
+            readonly request: AgentRequest;
+            readonly outcome: 'supported' | 'refused';
+            readonly requested?: EngineSelectionRecord;
+            readonly effective?: EngineSelectionRecord;
+        }>;
+        /** Observe actual process arguments or provider options, never the input request. */
+        observe(): {
+            readonly modelCalls: number;
+            readonly canRead: boolean;
+            readonly canWrite: boolean;
+        } | Promise<{
+            readonly modelCalls: number;
+            readonly canRead: boolean;
+            readonly canWrite: boolean;
+        }>;
+    };
+    /** Parse a final assistant part when the backend has no native schema mode. */
+    readonly parseStructuredResult?: (part: AgentResultPart, parts: readonly AgentResultPart[]) => JsonValue;
+    /**
+     * True for an adapter whose provider and model family come from the model
+     * it was given rather than from its own name (OpenCode, Devin). The kit then
+     * checks that the identity it reports is the one `modelIdentity` reads from
+     * the reported model, so two seats on one model cannot pass as two families.
+     */
+    readonly identityFromModel?: boolean;
+    open(scenario: EngineConformanceScenario): Engine | Promise<Engine>;
+}
+export interface EngineConformanceFailure {
+    readonly case: string;
+    readonly message: string;
+}
+export interface EngineConformanceReport {
+    readonly ok: boolean;
+    readonly cases: number;
+    readonly failures: readonly EngineConformanceFailure[];
+}
+export interface EngineAdapterConformanceReport extends EngineConformanceReport {
+    readonly unsupported: readonly {
+        readonly case: FeatureScenario;
+        readonly reason: string;
+    }[];
+}
+/** Run framework-free behavioral checks against an outside Engine adapter. */
+export declare function runEngineConformance(fixture: EngineConformanceFixture): Promise<EngineAdapterConformanceReport>;
+/** Throw one readable error when an outside Engine breaks the contract. */
+export declare function assertEngineConformance(fixture: EngineConformanceFixture): Promise<void>;
+export interface EngineAdmissionConformanceFixture {
+    readonly request: AgentRequest;
+    readonly selection: EngineSelectionRecord;
+    open(): Engine | Promise<Engine>;
+    /** No argument counts all model calls; a path/null counts that target. */
+    modelCalls(executable?: string | null): number | Promise<number>;
+    readonly cli?: {
+        /** Move bare-name lookup while keeping the admitted path runnable. */
+        moveLookup(): void | Promise<void>;
+        /** Same configuration, except an explicitly different absolute path. */
+        openDifferent(): Engine | Promise<Engine>;
+        /** A syntactically valid absolute path with no executable. */
+        openMissing(): Engine | Promise<Engine>;
+    };
+}
+export type EngineAdmissionConformanceReport = EngineConformanceReport | {
+    readonly kind: 'unsupported';
+    readonly adapter: string;
+};
+/** Check optional admission without imposing the full run-scenario protocol. */
+export declare function runEngineAdmissionConformance(fixture: EngineAdmissionConformanceFixture): Promise<EngineAdmissionConformanceReport>;
+export {};

package/dist/environment.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The Environment provider — the third axis, after Engine (where the agent
+ * thinks) and Workspace (where the code lives). Environment is where the code
+ * runs: local services, or a per-branch cloud preview. It lets the gate test the
+ * running thing, so "done" can mean "the e2e suite passes against the running
+ * preview", not just "unit tests pass against static files on disk".
+ *
+ * Like `Engine`, this is only an interface. API owns the interface and the
+ * runtime owns the lifecycle binding; the actual adapter (sst, Vercel, Docker, …) is
+ * provider-specific and lives in the consumer's loop definition, next to the
+ * deploy config it wraps. The runtime never takes a dependency on a deploy tool.
+ * Implement `up`, return a handle:
+ *
+ *   const sstEnv: Environment = {
+ *     name: 'sst',
+ *     async up(ws) {
+ *       const stage = slug(ws.branch);           // per-branch stage
+ *       const out = await sh('sst', ['deploy', '--stage', stage], ws.dir);
+ *       return {
+ *         url: out.url,
+ *         env: { BASE_URL: out.url },
+ *         down: () => sh('sst', ['remove', '--stage', stage], ws.dir),
+ *       };
+ *     },
+ *   };
+ */
+export interface EnvironmentWorkspace {
+    readonly dir: string;
+    readonly branch?: string;
+}
+/** A running environment for one workspace. Returned by `Environment.up`. */
+export interface EnvHandle {
+    /** Addressable base URL (a preview deployment, or a local server), if any. */
+    readonly url?: string;
+    /**
+     * Variables injected into gate commands, judge calls, and agent turns, e.g.
+     * `BASE_URL`, `DATABASE_URL`. This is how `commandSucceeds('playwright', …)`
+     * reaches the running preview.
+     */
+    readonly env: Record<string, string>;
+    /**
+     * Redeploy when the branch advances (a cloud preview that tracks commits).
+     * Optional: a local-services env has nothing to sync.
+     */
+    sync?(commit: string, signal: AbortSignal): Promise<void>;
+    /** Tear the environment down. */
+    down(signal: AbortSignal): Promise<void>;
+}
+/** Brings a workspace's code up so the gate can test the running thing. */
+export interface Environment {
+    readonly name: string;
+    up(workspace: EnvironmentWorkspace, signal: AbortSignal): Promise<EnvHandle>;
+}

package/dist/error.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared engine failure classification. Typed engine failures and compatible
+ * runtime codes take priority over process errors and message text.
+ *
+ * Default fallback treats auth, billing, missing executables, unavailable
+ * models, invalid configuration and exhausted long allowances as lasting for
+ * the run. Ambiguous limit wording is rate-limit, not evidence of quota.
+ * Rate limits and transient failures remain outside the default lasting set.
+ */
+import type { EngineFailureKind, EngineIncompleteResultEvidence, EngineSelectionRecord } from './contracts.js';
+export type { EngineFailureKind } from './contracts.js';
+export interface EngineErrorInit {
+    readonly kind: EngineFailureKind;
+    readonly message: string;
+    readonly cause?: unknown;
+    readonly retryAfterMs?: number;
+    readonly resetAt?: number;
+    readonly effective?: EngineSelectionRecord;
+}
+/** A provider or adapter failure with no runtime policy attached. */
+export declare class EngineError extends Error {
+    readonly kind: EngineFailureKind;
+    readonly retryAfterMs?: number;
+    readonly resetAt?: number;
+    readonly effective?: EngineSelectionRecord;
+    constructor(init: EngineErrorInit);
+}
+/** A failed engine turn that still produced measured, recordable evidence. */
+export declare class EngineIncompleteResultError extends EngineError {
+    readonly evidence: EngineIncompleteResultEvidence;
+    constructor(message: string, evidence: EngineIncompleteResultEvidence);
+}
+/** Failures that default fallback treats as lasting for the run. */
+export declare const LANE_DEAD_FAILURES: ReadonlySet<EngineFailureKind>;
+/** Classify a failed engine turn. Typed signals win over substring rules. */
+export declare function classifyEngineFailure(error: unknown): EngineFailureKind;

package/dist/events/conformance.d.ts

@@ -0,0 +1,20 @@
+import type { EventStore } from './store.js';
+export interface EventStoreConformanceOptions {
+    readonly maxEventPayloadBytes: number;
+    readonly maxAppendBatchBytes: number;
+    readonly knownSecrets: readonly string[];
+}
+export type EventStoreConformanceFactory = (options: EventStoreConformanceOptions) => EventStore | Promise<EventStore>;
+export interface EventStoreConformanceFailure {
+    readonly case: string;
+    readonly message: string;
+}
+export interface EventStoreConformanceReport {
+    readonly ok: boolean;
+    readonly cases: number;
+    readonly failures: readonly EventStoreConformanceFailure[];
+}
+/** Run framework-free checks against an outside EventStore implementation. */
+export declare function runEventStoreConformance(factory: EventStoreConformanceFactory): Promise<EventStoreConformanceReport>;
+/** Throw one readable error when an outside EventStore breaks the contract. */
+export declare function assertEventStoreConformance(factory: EventStoreConformanceFactory): Promise<void>;

package/dist/events/envelope.d.ts

@@ -0,0 +1,26 @@
+import { type JsonValue } from '../json.js';
+export type DomainEventId = string;
+export type EventStreamId = string;
+export type StorageNamespace = string;
+export type StreamRevision = number;
+export interface EventStreamRef {
+    readonly namespace: StorageNamespace;
+    readonly streamId: EventStreamId;
+}
+export interface NewDomainEvent<Type extends string = string, Version extends number = number, Payload extends JsonValue = JsonValue> {
+    readonly eventId: DomainEventId;
+    readonly type: Type;
+    readonly version: Version;
+    readonly timestamp: string;
+    readonly correlationId: string;
+    readonly causationId: DomainEventId | null;
+    readonly payload: Payload;
+}
+export interface DomainEventEnvelope<Type extends string = string, Version extends number = number, Payload extends JsonValue = JsonValue> extends NewDomainEvent<Type, Version, Payload> {
+    readonly envelopeVersion: 1;
+    readonly streamId: EventStreamId;
+    readonly revision: StreamRevision;
+}
+export declare function validateDomainEventId(value: unknown, path: string): string;
+export declare function validateNewDomainEvent(value: unknown): NewDomainEvent;
+export declare function validateDomainEventEnvelope(value: unknown): DomainEventEnvelope;

package/dist/events/store.d.ts

@@ -0,0 +1,15 @@
+import { type DomainEventEnvelope, type EventStreamRef, type NewDomainEvent, type StreamRevision } from './envelope.js';
+export type DomainEventBatch = readonly [
+    NewDomainEvent,
+    ...NewDomainEvent[]
+];
+export interface EventStore {
+    preflightAppend(stream: EventStreamRef, expectedRevision: StreamRevision, events: DomainEventBatch): Promise<void>;
+    read(stream: EventStreamRef, afterRevision?: StreamRevision): AsyncIterable<DomainEventEnvelope>;
+    append(stream: EventStreamRef, expectedRevision: StreamRevision, events: DomainEventBatch): Promise<StreamRevision>;
+}
+export { validateStorageId } from '../storage/id.js';
+export declare function validateEventStreamRef(value: unknown): EventStreamRef;
+export declare function validateStreamRevision(value: unknown, path: string): StreamRevision;
+export declare function validateDomainEventBatch(value: unknown): DomainEventBatch;
+export declare function findKnownSecretInEvents(knownSecrets: readonly string[], serializedBytes: string, events: readonly NewDomainEvent[]): string | undefined;

package/dist/graph-commands.d.ts

@@ -0,0 +1,23 @@
+import type { NodeId } from './graph-contract.js';
+import type { JsonValue } from './json.js';
+export interface DispatchGraphCommand<Input extends JsonValue = JsonValue> {
+    readonly kind: 'dispatch';
+    readonly nodeId: NodeId;
+    readonly input: Input;
+    /** Stable logical identity and location of this requested node occurrence. */
+    readonly position: string;
+}
+export interface PauseGraphCommand {
+    readonly kind: 'pause';
+    readonly reason: string;
+}
+export interface CompleteGraphCommand<Output extends JsonValue = JsonValue> {
+    readonly kind: 'complete';
+    readonly output: Output;
+}
+export interface FailGraphCommand {
+    readonly kind: 'fail';
+    readonly code: string;
+    readonly message: string;
+}
+export type GraphCommand<Input extends JsonValue = JsonValue, Output extends JsonValue = JsonValue> = DispatchGraphCommand<Input> | PauseGraphCommand | CompleteGraphCommand<Output> | FailGraphCommand;

package/dist/graph-contract.d.ts

@@ -0,0 +1,48 @@
+import type { JsonObject, JsonValue, Sha256Digest } from './json.js';
+export type RunBrief = JsonObject;
+export interface GraphValidationIssue {
+    readonly code: string;
+    readonly path: string;
+    readonly message: string;
+}
+export declare class GraphValidationError extends Error {
+    readonly issues: readonly GraphValidationIssue[];
+    constructor(message: string, issues: readonly GraphValidationIssue[]);
+}
+export type GraphId = string;
+export type NodeId = string;
+export type EdgeId = string;
+export interface GraphNode<Data extends JsonValue = JsonValue> extends JsonObject {
+    readonly id: NodeId;
+    readonly data: Data;
+}
+export interface GraphEdge<Data extends JsonValue = JsonValue> extends JsonObject {
+    readonly id: EdgeId;
+    readonly source: NodeId;
+    readonly target: NodeId;
+    readonly data: Data;
+}
+export interface GraphDefinition<NodeData extends JsonValue = JsonValue, EdgeData extends JsonValue = JsonValue, GraphData extends JsonValue = JsonValue> extends JsonObject {
+    readonly id: GraphId;
+    readonly definitionVersion: number;
+    readonly data: GraphData;
+    readonly nodes: readonly GraphNode<NodeData>[];
+    readonly edges: readonly GraphEdge<EdgeData>[];
+}
+export interface CompiledGraphDefinition<Definition extends GraphDefinition = GraphDefinition> extends JsonObject {
+    readonly value: Definition;
+    readonly canonicalJson: string;
+    readonly digest: Sha256Digest;
+}
+type DefinitionNode<Definition extends GraphDefinition> = Definition['nodes'][number];
+type DefinitionEdge<Definition extends GraphDefinition> = Definition['edges'][number];
+export interface GraphKernel<Definition extends GraphDefinition = GraphDefinition> {
+    readonly definition: CompiledGraphDefinition<Definition>;
+    node(id: NodeId): DefinitionNode<Definition> | undefined;
+    edge(id: EdgeId): DefinitionEdge<Definition> | undefined;
+    predecessors(id: NodeId): readonly NodeId[];
+    successors(id: NodeId): readonly NodeId[];
+    inboundEdges(id: NodeId): readonly DefinitionEdge<Definition>[];
+    outboundEdges(id: NodeId): readonly DefinitionEdge<Definition>[];
+}
+export {};

package/dist/graph-executor.d.ts

@@ -0,0 +1,61 @@
+import type { Memory } from './memory-types.js';
+import type { GraphCommand } from './graph-commands.js';
+import type { CompiledGraphType } from './graph-type.js';
+import type { JsonObject, JsonValue } from './json.js';
+import type { ExecutionTarget, AgentResultPart, EngineSelectionRecord, Engine } from './contracts.js';
+import type { AttemptBudgetPolicy, TokenBudget } from './budget.js';
+import type { NodeDataContext } from './node-data-context.js';
+import type { ResultContract } from './result-contract.js';
+import type { RunStorageBinding } from './run-definition.js';
+import type { NodeWorkspacePolicy } from './workspace/policy.js';
+import type { ActionDecision } from './action-decision.js';
+import type { PreflightPauseResult, PreflightFailureResult } from './preflight-result.js';
+export type GraphExecutionErrorCode = 'ABORTED' | 'DUPLICATE_POSITION' | 'EMPTY_DECISION' | 'ENGINE_IDENTITY_UNRESOLVED' | 'INVALID_EVENT' | 'INVALID_PREFLIGHT_CONFIG' | 'MISSING_ENGINE_BINDING' | 'MISSING_MEMORY' | 'MISSING_NODE_BINDING' | 'PROTOCOL' | 'RESUME_EVENT_MISMATCH' | 'STORED_GRAPH_MISMATCH';
+export declare class GraphExecutionError extends Error {
+    readonly code: GraphExecutionErrorCode;
+    constructor(code: GraphExecutionErrorCode, message: string, options?: ErrorOptions);
+}
+export interface GraphNodeBinding {
+    readonly prompt: ((input: JsonValue) => string) | null;
+    readonly scratchDirectory: string;
+    readonly workspace: NodeWorkspacePolicy;
+    readonly trustedCaller: JsonObject;
+    readonly permissions: readonly string[];
+    readonly policy: AttemptBudgetPolicy;
+    readonly resultContract: ResultContract | null;
+    readonly runData: ((context: NodeDataContext) => Promise<JsonValue>) | null;
+    readonly parseResult: ((part: AgentResultPart, parts: readonly AgentResultPart[]) => JsonValue) | null;
+    readonly tokenBudget: TokenBudget | null;
+    /** Whether node code may run again after a crash leaves its outcome unknown. */
+    readonly retrySafe?: boolean;
+    decideAction(): Promise<ActionDecision>;
+}
+export interface GraphEngineBinding {
+    readonly target: ExecutionTarget;
+    readonly selection: EngineSelectionRecord;
+    readonly engine: Engine;
+    readonly hardTokenLimitEnforceable: boolean;
+}
+export interface GraphExecutorOptions {
+    readonly runId: string;
+    readonly graph: CompiledGraphType;
+    readonly storage: RunStorageBinding;
+    readonly nodes: Readonly<Record<string, GraphNodeBinding>>;
+    readonly engines: readonly GraphEngineBinding[];
+    readonly preflightScratchDirectory?: string;
+    readonly bindings?: {
+        readonly memory?: Memory;
+    };
+}
+export type GraphExecutorResult = Extract<GraphCommand, {
+    readonly kind: 'pause' | 'complete' | 'fail';
+}> | PreflightPauseResult | PreflightFailureResult | {
+    readonly kind: 'waiting';
+    readonly positions: readonly string[];
+};
+export interface GraphExecutor {
+    run(signal: AbortSignal): Promise<GraphExecutorResult>;
+    resume(target: string | {
+        readonly preflightEventId: string;
+    }, signal: AbortSignal): Promise<GraphExecutorResult>;
+}

package/dist/graph-kernel.d.ts

@@ -0,0 +1,2 @@
+import { type GraphDefinition, type CompiledGraphDefinition } from './graph-contract.js';
+export declare function compileGraphDefinition<Definition extends GraphDefinition>(definition: Definition): CompiledGraphDefinition<Definition>;