Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

refactor(runtime): replace content-addressed artifacts with resources

kashorine8dc1d07b62a
diff --git a/docs/guide/packages.md b/docs/guide/packages.md
index a473e55f..9d7b93a7 100644
--- a/docs/guide/packages.md
+++ b/docs/guide/packages.md
@@ -57,7 +57,7 @@ Reusable values and deterministic building blocks. They support video authoring
film's creative structure or call an external service.
```text
-@hypit/artifact content-addressed bytes
+@hypit/artifact Runtime-referenced byte values
@hypit/component-kit Producer and validator registration
@hypit/text graph-native text templates
@hypit/media media values
@@ -149,8 +149,8 @@ project Build Result repository are the intentional package-selected boundaries.
@hypit/runtime-host-node Node Runtime Host ABI
@hypit/runtime-local local Worker and assembly
@hypit/store-sqlite SQLite state
-@hypit/artifact-store-fs internal filesystem working Artifacts
-@hypit/artifact-store-s3 library for Runtime implementations needing S3 working Artifacts
+@hypit/resource-store-fs internal filesystem working Resources
+@hypit/resource-store-s3 library for Runtime implementations needing S3 working Resources
@hypit/build-result storage-neutral project Result model
@hypit/build-result-kit Build Result repository package ABI
@hypit/build-result-fs default project Result repository
diff --git a/docs/quickstart/composition.md b/docs/quickstart/composition.md
index 66582628..1be50db1 100644
--- a/docs/quickstart/composition.md
+++ b/docs/quickstart/composition.md
@@ -99,7 +99,7 @@ The renderer:
4. Mixes the audio Tracks
5. Muxes video + audio into the final MP4
-**Output:** `{final.video}` — the finished video as an ordinary content-addressed `BlobArtifact`.
+**Output:** `{final.video}` — the finished video as an ordinary Resource-backed `BlobArtifact`.
This is the most common Build Target, and it can also be connected directly to later Blob consumers
such as media trimming, audio/frame extraction or a model reference input.
diff --git a/docs/quickstart/generation.md b/docs/quickstart/generation.md
index 7a88f15c..661a11fe 100644
--- a/docs/quickstart/generation.md
+++ b/docs/quickstart/generation.md
@@ -21,7 +21,7 @@ Every component shown here must be imported by its package specifier before use:
## media:Image
-Declares a content-addressed image asset from a local file.
+Declares an image Resource from a local file.
```svml
<media:Image id="presenter" src="./assets/presenter.png"/>
@@ -37,7 +37,7 @@ The image is referenced downstream via `{presenter}` — for example, as a chara
## media:Audio
-Declares a content-addressed audio asset from a local file.
+Declares an audio Resource from a local file.
```svml
<media:Audio id="presenter-voice" src="./assets/presenter-voice.mp3"/>
diff --git a/docs/quickstart/styles.md b/docs/quickstart/styles.md
index f0e21ae3..0bbe0268 100644
--- a/docs/quickstart/styles.md
+++ b/docs/quickstart/styles.md
@@ -368,7 +368,7 @@ import the private pre-release catalog and select only the faces the Author Grap
The catalog contains 109 open families across handwriting, script, display, sans, serif,
monospace, CJK, world-script and Emoji categories. Fontsource dependencies are pinned to `5.3.0`;
the Chromium-compatible COLRv1 Emoji package is pinned separately. The compiler hashes installed
-bytes into content-addressed font values. It performs no download during a build, and the Runtime
+bytes into Resource-backed font values. It performs no download during a build, and the Runtime
never guesses a font:
```svml
diff --git a/docs/zh/guide/author-packages.md b/docs/zh/guide/author-packages.md
index 2a5d7740..cd56fac6 100644
--- a/docs/zh/guide/author-packages.md
+++ b/docs/zh/guide/author-packages.md
@@ -71,7 +71,6 @@ export const myComponentMarkupSurfaces = [{
mode: "structured",
outputs: [ /* 这段语法可以创作的 Type */ ],
vocabulary: { /* 这个元素是什么、长什么样 —— 见第 5 步 */ },
- implementation: { digest: "sha256:..." },
}] as const;
```
diff --git a/docs/zh/guide/packages.md b/docs/zh/guide/packages.md
index 1a4607d1..9e7068ab 100644
--- a/docs/zh/guide/packages.md
+++ b/docs/zh/guide/packages.md
@@ -140,8 +140,8 @@ Frontend;不存在一个认识全部语法的中央解析器。
@hypit/runtime-host-node Node Runtime Host ABI
@hypit/runtime-local 本地 Worker 与组装
@hypit/store-sqlite SQLite 状态
-@hypit/artifact-store-fs Runtime 内部文件系统临时 Artifact
-@hypit/artifact-store-s3 供需要 S3 临时 Artifact 的 Runtime 实现使用的库
+@hypit/resource-store-fs Runtime 内部文件系统临时 Resource
+@hypit/resource-store-s3 供需要 S3 临时 Resource 的 Runtime 实现使用的库
@hypit/build-result 存储无关的项目 Result 模型
@hypit/build-result-kit Build Result 仓库包 ABI
@hypit/build-result-fs 默认项目 Result 仓库
diff --git a/docs/zh/guide/providers.md b/docs/zh/guide/providers.md
index 6b2fb827..c2427e60 100644
--- a/docs/zh/guide/providers.md
+++ b/docs/zh/guide/providers.md
@@ -211,7 +211,7 @@ hypit doctor hypit.runtime.json
| `provider-media-local` | 本地进程:不经 shell 的 ffprobe/ffmpeg,执行有界 |
| `provider-whisperx-local` | 本地 HTTP 服务:带热模型,单次准入并发 |
| `provider-hyperframes-local` | 本地进程:Chrome 渲染,带 worker 并行与输出探测校验 |
-| `provider-hyperframes-aws-lambda` | 远程可恢复任务:确定性 Step Functions 提交、轮询与 S3 流式落库 |
+| `provider-hyperframes-aws-lambda` | 远程异步任务:按 Operation 自行暂存、Step Functions 轮询与结果流式回收 |
| `provider-image-opencv-local` | 本地 Python:有界的 OpenCV/NumPy,配合锁定的 Python 环境 |
| `provider-media-aws-lambda` | 远程同步 Lambda:与本地媒体相同的九项能力 |
| `provider-xiaomi-mimo` | 远程即时 API:把精确 MiMo VoiceDesign 请求落成持久化音频 Artifact |
diff --git a/package.json b/package.json
index a564da6b..19998e4f 100644
--- a/package.json
+++ b/package.json
@@ -50,17 +50,15 @@
"test:image-opencv": "node test/run.mjs image-opencv",
"smoke:kie": "node --import tsx packages/provider-kie/test/live-smoke.ts",
"hypit": "node bin/hypit.mjs",
- "studio": "pnpm --filter @hypit/studio exec node --import tsx start.ts",
- "build:media-lambda": "pnpm --filter @hypit/media-lambda build",
- "build:media-lambda-layer": "pnpm --filter @hypit/media-lambda build:layer"
+ "studio": "pnpm --filter @hypit/studio exec node --import tsx start.ts"
},
"engines": {
"node": ">=22"
},
"devDependencies": {
"@hypit/artifact": "workspace:*",
- "@hypit/artifact-store-fs": "workspace:*",
- "@hypit/artifact-store-s3": "workspace:*",
+ "@hypit/resource-store-fs": "workspace:*",
+ "@hypit/resource-store-s3": "workspace:*",
"@hypit/build-result": "workspace:*",
"@hypit/build-result-fs": "workspace:*",
"@hypit/build-result-kit": "workspace:*",
@@ -107,7 +105,6 @@
"@hypit/provider-hypihub": "workspace:*",
"@hypit/provider-kie": "workspace:*",
"@hypit/provider-vertex": "workspace:*",
- "@hypit/provider-media-aws-lambda": "workspace:*",
"@hypit/provider-media-local": "workspace:*",
"@hypit/preview-mock": "workspace:*",
"@hypit/provider-whisperx-local": "workspace:*",
diff --git a/packages/artifact-store-fs/src/index.ts b/packages/artifact-store-fs/src/index.ts
deleted file mode 100644
index 5d0c094b..00000000
--- a/packages/artifact-store-fs/src/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { FileArtifactStore } from "./store.js";
-export type * from "./store.js";
diff --git a/packages/artifact-store-fs/src/store.ts b/packages/artifact-store-fs/src/store.ts
deleted file mode 100644
index a4c9c280..00000000
--- a/packages/artifact-store-fs/src/store.ts
+++ /dev/null
@@ -1,138 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import {
- link,
- mkdir,
- open as openFile,
- rm,
- stat,
-} from "node:fs/promises";
-import { dirname, join, resolve } from "node:path";
-
-import { isDigest } from "@hypit/protocol";
-import type { BlobRef, Digest } from "@hypit/protocol";
-import type { ArtifactStore } from "@hypit/runtime";
-
-function digestPath(root: string, digest: Digest): string {
- if (!isDigest(digest)) throw new Error("Artifact digest is invalid");
- const [algorithm, hex] = digest.split(":");
- if (algorithm !== "sha256" || hex === undefined) throw new Error(`unsupported Artifact digest ${digest}`);
- return join(root, algorithm, hex.slice(0, 2), hex);
-}
-
-function isNodeError(error: unknown, code: string): boolean {
- return error instanceof Error && "code" in error && error.code === code;
-}
-
-/** Project-local content-addressed bytes. Metadata remains in the typed BlobRef that names them. */
-export class FileArtifactStore implements ArtifactStore {
- readonly root: string;
-
- constructor(root: string) {
- if (root.trim().length === 0) throw new Error("Artifact root must not be empty");
- this.root = resolve(root);
- }
-
- async put(bytes: Uint8Array, mediaType: string): Promise<BlobRef> {
- const copy = Uint8Array.from(bytes);
- return await this.putStream((async function* () { yield copy; })(), mediaType);
- }
-
- async putStream(chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<BlobRef> {
- if (mediaType.trim().length === 0) throw new Error("Artifact mediaType must not be empty");
- const incoming = join(this.root, ".incoming");
- await mkdir(incoming, { recursive: true });
- const resource = `res_${randomUUID()}`;
- const temporary = join(incoming, resource);
- const handle = await openFile(temporary, "wx");
- const hash = createHash("sha256");
- let size = 0;
- try {
- try {
- for await (const value of chunks) {
- if (!(value instanceof Uint8Array)) throw new Error("Artifact stream yielded non-bytes");
- const chunk = Uint8Array.from(value);
- hash.update(chunk);
- size += chunk.byteLength;
- if (!Number.isSafeInteger(size)) throw new Error("Artifact stream exceeds the supported size");
- let offset = 0;
- while (offset < chunk.byteLength) {
- const written = await handle.write(chunk, offset, chunk.byteLength - offset);
- offset += written.bytesWritten;
- }
- }
- } finally {
- await handle.close();
- }
- } catch (error) {
- await rm(temporary, { force: true });
- throw error;
- }
- const digest = `sha256:${hash.digest("hex")}` as Digest;
- const path = digestPath(this.root, digest);
- await mkdir(dirname(path), { recursive: true });
- try {
- await link(temporary, path);
- } catch (error) {
- if (!isNodeError(error, "EEXIST")) {
- await rm(temporary, { force: true });
- throw error;
- }
- }
- await rm(temporary, { force: true });
- return { kind: "blob", resource, digest, size, mediaType };
- }
-
- async get(digest: Digest): Promise<Uint8Array | undefined> {
- const stream = await this.open(digest);
- if (stream === undefined) return undefined;
- const chunks: Uint8Array[] = [];
- let size = 0;
- for await (const chunk of stream) {
- chunks.push(chunk);
- size += chunk.byteLength;
- }
- const bytes = new Uint8Array(size);
- let offset = 0;
- for (const chunk of chunks) {
- bytes.set(chunk, offset);
- offset += chunk.byteLength;
- }
- return bytes;
- }
-
- async open(digest: Digest): Promise<AsyncIterable<Uint8Array> | undefined> {
- const path = digestPath(this.root, digest);
- try {
- if (!(await stat(path)).isFile()) throw new Error(`Artifact ${digest} is not a file`);
- } catch (error) {
- if (isNodeError(error, "ENOENT")) return undefined;
- throw error;
- }
- return (async function* () {
- const handle = await openFile(path, "r");
- try {
- const buffer = new Uint8Array(1024 * 1024);
- let position = 0;
- while (true) {
- const result = await handle.read(buffer, 0, buffer.byteLength, position);
- if (result.bytesRead === 0) break;
- position += result.bytesRead;
- const chunk = buffer.slice(0, result.bytesRead);
- yield chunk;
- }
- } finally {
- await handle.close();
- }
- })();
- }
-
- async has(digest: Digest): Promise<boolean> {
- try {
- return (await stat(digestPath(this.root, digest))).isFile();
- } catch (error) {
- if (isNodeError(error, "ENOENT")) return false;
- throw error;
- }
- }
-
-}
diff --git a/packages/artifact-store-s3/src/index.ts b/packages/artifact-store-s3/src/index.ts
deleted file mode 100644
index fff882f2..00000000
--- a/packages/artifact-store-s3/src/index.ts
+++ /dev/null
@@ -1,4 +0,0 @@
-export { AwsS3ObjectClient } from "./client.js";
-export type { S3ObjectClient } from "./client.js";
-export { S3ArtifactStore, createS3ArtifactStore, s3ArtifactKey, s3ArtifactStoreModuleRef } from "./store.js";
-export type * from "./store.js";
diff --git a/packages/artifact-store-s3/src/store.ts b/packages/artifact-store-s3/src/store.ts
deleted file mode 100644
index f0a2b97c..00000000
--- a/packages/artifact-store-s3/src/store.ts
+++ /dev/null
@@ -1,282 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-
-import { isDigest } from "@hypit/protocol";
-import type { BlobRef, Digest } from "@hypit/protocol";
-import type { ArtifactStore } from "@hypit/runtime";
-
-import { AwsS3ObjectClient } from "./client.js";
-import type { S3ObjectClient } from "./client.js";
-
-export const s3ArtifactStoreModuleRef = {
- name: "@hypit/artifact-store-s3",
- version: "1",
-} as const;
-
-/**
- * Where an Artifact lives in a bucket, given its digest.
- *
- * Exported because a remote worker that reads and writes the same bucket must
- * address objects identically. Two statements of this rule would be two
- * different stores wearing one bucket name.
- */
-export function s3ArtifactKey(prefix: string | undefined, digest: Digest): string {
- if (!isDigest(digest)) throw new Error("Artifact digest is invalid");
- const [algorithm, hex] = digest.split(":");
- if (algorithm !== "sha256" || hex === undefined) throw new Error(`unsupported Artifact digest ${digest}`);
- const normalized = normalizeS3ArtifactPrefix(prefix);
- const relative = `${algorithm}/${hex.slice(0, 2)}/${hex}`;
- return normalized.length === 0 ? relative : `${normalized}/${relative}`;
-}
-
-type S3Location = {
- readonly bucket: string;
- readonly prefix?: string;
- readonly expectedBucketOwner?: string;
-};
-
-export type S3ArtifactStoreOptions = S3Location & {
- readonly client: S3ObjectClient;
- /** Bytes buffered before a part is sent. S3 requires at least 5 MiB per non-final part. */
- readonly partSizeBytes?: number;
-};
-
-export type CreateS3ArtifactStorePackageOptions = S3Location & {
- readonly instance?: string;
- readonly partSizeBytes?: number;
- readonly region?: string;
- readonly endpoint?: string;
- readonly forcePathStyle?: boolean;
- /** Injection point for tests, MinIO and specially configured trusted AWS clients. */
- readonly client?: S3ObjectClient;
-};
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-export function normalizeS3ArtifactPrefix(prefix: string | undefined): string {
- if (prefix === undefined || prefix.length === 0) return "";
- const normalized = prefix.replace(/^\/+|\/+$/gu, "");
- assert(normalized.length > 0, "S3 Artifact prefix must contain a non-slash character");
- assert(!normalized.split("/").some((part) => part === "." || part === ".."),
- "S3 Artifact prefix cannot contain dot path segments");
- return normalized;
-}
-
-function positiveInteger(value: number, subject: string): number {
- assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive safe integer`);
- return value;
-}
-
-/**
- * Content-addressed S3 ArtifactStore.
- *
- * The streaming facet is detected by method presence, so this
- * store attaches it only when the injected client can back it. Claiming a
- * facet and then throwing would be worse than not claiming it: a deployment
- * would discover the gap during a Build rather than when it chose the client.
- */
-export class S3ArtifactStore implements ArtifactStore {
- readonly #client: S3ObjectClient;
- readonly #bucket: string;
- readonly #prefix: string;
- readonly #expectedBucketOwner: string | undefined;
- readonly #partSizeBytes: number;
- /** Present only when the client can stream and upload in parts. */
- readonly open?: (digest: Digest) => Promise<AsyncIterable<Uint8Array> | undefined>;
- readonly putStream?: (chunks: AsyncIterable<Uint8Array>, mediaType: string) => Promise<BlobRef>;
-
- constructor(options: S3ArtifactStoreOptions) {
- assert(options.bucket.trim().length > 0, "S3 Artifact bucket must not be empty");
- if (options.expectedBucketOwner !== undefined) {
- assert(options.expectedBucketOwner.trim().length > 0, "expected S3 bucket owner must not be empty");
- }
- this.#client = options.client;
- this.#bucket = options.bucket;
- this.#prefix = normalizeS3ArtifactPrefix(options.prefix);
- this.#expectedBucketOwner = options.expectedBucketOwner;
- this.#partSizeBytes = positiveInteger(options.partSizeBytes ?? 16 * 1024 * 1024, "partSizeBytes");
- assert(this.#partSizeBytes >= 5 * 1024 * 1024, "S3 requires multipart parts of at least 5 MiB");
- const client = options.client;
- if (client.open !== undefined && client.createMultipart !== undefined && client.uploadPart !== undefined
- && client.completeMultipart !== undefined && client.copy !== undefined) {
- this.open = (digest) => this.#openStream(digest);
- this.putStream = (chunks, mediaType) => this.#putStream(chunks, mediaType);
- }
- }
-
- key(digest: Digest): string {
- return s3ArtifactKey(this.#prefix, digest);
- }
-
- async put(bytes: Uint8Array, mediaType: string): Promise<BlobRef> {
- assert(mediaType.trim().length > 0, "Artifact mediaType must not be empty");
- const copy = Uint8Array.from(bytes);
- const hash = createHash("sha256").update(copy);
- const hex = hash.copy().digest("hex");
- const digest = `sha256:${hex}` as Digest;
- const input = {
- Bucket: this.#bucket,
- Key: this.key(digest),
- Body: copy,
- ContentLength: copy.byteLength,
- ContentType: mediaType,
- ChecksumSHA256: hash.digest("base64"),
- ...(this.#expectedBucketOwner === undefined
- ? {}
- : { ExpectedBucketOwner: this.#expectedBucketOwner }),
- } as const;
- await this.#client.put(input);
- return { kind: "blob", resource: `res_${randomUUID()}`, digest, size: copy.byteLength, mediaType };
- }
-
- async get(digest: Digest): Promise<Uint8Array | undefined> {
- const bytes = await this.#client.get({
- Bucket: this.#bucket,
- Key: this.key(digest),
- ...(this.#expectedBucketOwner === undefined
- ? {}
- : { ExpectedBucketOwner: this.#expectedBucketOwner }),
- });
- if (bytes === undefined) return undefined;
- return Uint8Array.from(bytes);
- }
-
- async has(digest: Digest): Promise<boolean> {
- if (this.#client.head === undefined) return (await this.#client.get({
- Bucket: this.#bucket,
- Key: this.key(digest),
- ...(this.#expectedBucketOwner === undefined
- ? {}
- : { ExpectedBucketOwner: this.#expectedBucketOwner }),
- })) !== undefined;
- return (await this.#client.head({
- Bucket: this.#bucket,
- Key: this.key(digest),
- ...(this.#expectedBucketOwner === undefined
- ? {}
- : { ExpectedBucketOwner: this.#expectedBucketOwner }),
- })) !== undefined;
- }
-
- async #openStream(digest: Digest): Promise<AsyncIterable<Uint8Array> | undefined> {
- const chunks = await this.#client.open!({
- Bucket: this.#bucket,
- Key: this.key(digest),
- ...(this.#expectedBucketOwner === undefined
- ? {}
- : { ExpectedBucketOwner: this.#expectedBucketOwner }),
- });
- if (chunks === undefined) return undefined;
- return chunks;
- }
-
- /**
- * Multipart upload to a staging key, then a server-side copy onto the
- * content-addressed key.
- *
- * The detour exists because S3 needs the destination key before the first
- * part, and a content-addressed key is not known until the last byte has been
- * hashed. The copy is server-side, so the bytes cross the wire once.
- */
- async #putStream(chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<BlobRef> {
- assert(mediaType.trim().length > 0, "Artifact mediaType must not be empty");
- const client = this.#client as Required<S3ObjectClient>;
- const owner = this.#expectedBucketOwner === undefined
- ? {}
- : { ExpectedBucketOwner: this.#expectedBucketOwner };
- const staging = `${this.#prefix.length === 0 ? "" : `${this.#prefix}/`}.incoming/${randomUUID()}`;
- const uploadId = await client.createMultipart({
- Bucket: this.#bucket, Key: staging, ContentType: mediaType, ...owner,
- });
- const hash = createHash("sha256");
- const parts: { PartNumber: number; ETag: string }[] = [];
- let size = 0;
- try {
- let pending: Uint8Array[] = [];
- let pendingBytes = 0;
- const flush = async (): Promise<void> => {
- if (pendingBytes === 0) return;
- const body = new Uint8Array(pendingBytes);
- let offset = 0;
- for (const piece of pending) {
- body.set(piece, offset);
- offset += piece.byteLength;
- }
- pending = [];
- pendingBytes = 0;
- const partNumber = parts.length + 1;
- const { etag } = await client.uploadPart!({
- Bucket: this.#bucket, Key: staging, UploadId: uploadId,
- PartNumber: partNumber, Body: body, ContentLength: body.byteLength, ...owner,
- });
- parts.push({ PartNumber: partNumber, ETag: etag });
- };
- for await (const value of chunks) {
- if (!(value instanceof Uint8Array)) throw new Error("Artifact stream yielded non-bytes");
- const chunk = Uint8Array.from(value);
- hash.update(chunk);
- size += chunk.byteLength;
- if (!Number.isSafeInteger(size)) throw new Error("Artifact stream exceeds the supported size");
- pending.push(chunk);
- pendingBytes += chunk.byteLength;
- if (pendingBytes >= this.#partSizeBytes) await flush();
- }
- await flush();
- // Only now can the stream be known to have been empty. S3 rejects a
- // multipart upload with no parts, and an empty Artifact is a legitimate
- // one, so that case still sends a single empty part.
- if (parts.length === 0) {
- const { etag } = await client.uploadPart({
- Bucket: this.#bucket, Key: staging, UploadId: uploadId,
- PartNumber: 1, Body: new Uint8Array(0), ContentLength: 0, ...owner,
- });
- parts.push({ PartNumber: 1, ETag: etag });
- }
- await client.completeMultipart({
- Bucket: this.#bucket, Key: staging, UploadId: uploadId,
- MultipartUpload: { Parts: parts }, ...owner,
- });
- } catch (error) {
- await client.abortMultipart?.({
- Bucket: this.#bucket, Key: staging, UploadId: uploadId, ...owner,
- }).catch(() => undefined);
- throw error;
- }
- const digest = `sha256:${hash.digest("hex")}` as Digest;
- try {
- await client.copy({
- Bucket: this.#bucket,
- Key: this.key(digest),
- CopySource: `${this.#bucket}/${staging}`,
- ContentType: mediaType,
- MetadataDirective: "REPLACE",
- ...owner,
- });
- } finally {
- await client.delete?.({ Bucket: this.#bucket, Key: staging, ...owner }).catch(() => undefined);
- }
- return { kind: "blob", resource: `res_${randomUUID()}`, digest, size, mediaType };
- }
-
-}
-
-export function createS3ArtifactStore(
- options: CreateS3ArtifactStorePackageOptions,
-): S3ArtifactStore {
- const prefix = normalizeS3ArtifactPrefix(options.prefix);
- const client = options.client ?? new AwsS3ObjectClient({
- ...(options.region === undefined ? {} : { region: options.region }),
- ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
- ...(options.forcePathStyle === undefined ? {} : { forcePathStyle: options.forcePathStyle }),
- });
- return new S3ArtifactStore({
- client,
- bucket: options.bucket,
- ...(options.partSizeBytes === undefined ? {} : { partSizeBytes: options.partSizeBytes }),
- ...(prefix.length === 0 ? {} : { prefix }),
- ...(options.expectedBucketOwner === undefined
- ? {}
- : { expectedBucketOwner: options.expectedBucketOwner }),
- });
-}
diff --git a/packages/artifact/README.md b/packages/artifact/README.md
index 221ceb37..2b0403f1 100644
--- a/packages/artifact/README.md
+++ b/packages/artifact/README.md
@@ -1,10 +1,10 @@
# `@hypit/artifact`
-Domain-neutral nominal contract for one content-addressed byte Artifact.
+Domain-neutral nominal contract for one byte Artifact referenced by a Runtime Resource id.
`BlobArtifact` wraps the Protocol `BlobRef` storage form in an owner-defined `TypeRef`, allowing any
domain to place files, model outputs or other immutable bytes on Graph edges without borrowing a
media/video type. Artifact storage and transfer remain separate Runtime ports implemented by
-packages such as `@hypit/artifact-store-fs` and `@hypit/artifact-store-s3`.
+packages such as `@hypit/resource-store-fs` and `@hypit/resource-store-s3`.
The package has no filesystem, network, media or Provider behavior.
diff --git a/packages/audio-track-studio/src/index.ts b/packages/audio-track-studio/src/index.ts
index 7504f4d5..cb84751b 100644
--- a/packages/audio-track-studio/src/index.ts
+++ b/packages/audio-track-studio/src/index.ts
@@ -13,7 +13,7 @@ function projectAudio(context: StudioTrackCompanionContext): readonly StudioEnti
endFrameExclusive: item.window.endFrameExclusive,
stackOrder: Number.MIN_SAFE_INTEGER,
sourceTypes: [audioTrackTypes.clipSpec],
- preview: artifactPreview("audio", item.source.artifact.digest),
+ preview: artifactPreview("audio", item.source.artifact.resource),
}));
return childEntities(context, items, "audio-clip", "standard").map((entity, index) => {
const item = items[index]!;
diff --git a/packages/audio-track/src/program.ts b/packages/audio-track/src/program.ts
index fba3830f..d6ecae2e 100644
--- a/packages/audio-track/src/program.ts
+++ b/packages/audio-track/src/program.ts
@@ -8,7 +8,7 @@ import {
programSpaceSampleFrames,
} from "@hypit/program-space";
import type { ProgramSpace } from "@hypit/program-space";
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import { assertTemporalWindowFor, temporalDurationInSamples } from "@hypit/temporal";
import type { ProjectedWindow, TemporalDuration } from "@hypit/temporal";
@@ -170,7 +170,7 @@ export function assertAudioTrackProgram(value: AudioTrackProgram): void {
assert(Number.isSafeInteger(item.window.startFrame) && item.window.startFrame >= 0
&& Number.isSafeInteger(item.window.endFrameExclusive)
&& item.window.endFrameExclusive > item.window.startFrame, `Audio Item ${item.id} window is invalid.`);
- assert(isDigest(item.source.artifact.digest) && item.source.artifact.mediaType === "audio/wav"
+ assert(isResourceId(item.source.artifact.resource) && item.source.artifact.mediaType === "audio/wav"
&& Number.isSafeInteger(item.source.sampleFrames) && item.source.sampleFrames > 0,
`Audio Item ${item.id} source is invalid.`);
assert(item.trim.startSample >= 0 && item.trim.endSampleExclusive > item.trim.startSample
diff --git a/packages/audio-track/test/audio-track.test.ts b/packages/audio-track/test/audio-track.test.ts
index f524cf06..f682312c 100644
--- a/packages/audio-track/test/audio-track.test.ts
+++ b/packages/audio-track/test/audio-track.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import { projectMomentWindow, projectProgramWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";
import type { TemporalWindowProjection } from "../../../test/temporal-fixture.js";
@@ -61,7 +61,7 @@ function media(id: string, sampleFrames: number): SynchronizedMedia {
frameCount: Math.max(1, Math.round(sampleFrames / 1_600)),
},
audio: {
- artifact: { kind: "blob", digest: fixtureDigest(`audio:${id}`), size: sampleFrames * 4, mediaType: "audio/wav" },
+ artifact: { kind: "blob", resource: fixtureResource(`audio:${id}`), size: sampleFrames * 4, mediaType: "audio/wav" },
},
};
}
@@ -259,7 +259,7 @@ test("dynamic Fragment keeps every material and temporal dependency as an explic
test("the self-described Audio Surface parses into the same finite Producer graph", async () => {
const fixtureModule = { name: "example.audio-inputs", version: "1" } as const;
- const fixtureSurfaceDigest = fixtureDigest("example.audio-inputs/surface@1");
+ const fixtureSurfaceDigest = fixtureResource("example.audio-inputs/surface@1");
const fixtureSurface = {
name: "inputs", tag: "Inputs", mode: "structured",
outputs: [mediaTypes.synchronized, semanticTrackTypes.track],
diff --git a/packages/background-removal/src/program.ts b/packages/background-removal/src/program.ts
index bc0e330b..f8f7808d 100644
--- a/packages/background-removal/src/program.ts
+++ b/packages/background-removal/src/program.ts
@@ -1,4 +1,4 @@
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import type { BackgroundRemovalRequest } from "./types.js";
@@ -7,7 +7,7 @@ function assert(condition: unknown, message: string): asserts condition {
}
export function assertBackgroundRemovalRequest(value: BackgroundRemovalRequest): void {
- assert(value.source.kind === "blob" && isDigest(value.source.digest)
+ assert(value.source.kind === "blob" && isResourceId(value.source.resource)
&& Number.isSafeInteger(value.source.size) && value.source.size >= 0
&& value.source.mediaType.startsWith("image/"), "Background Removal source must be an image Blob Artifact.");
}
diff --git a/packages/background-removal/test/background-removal.test.ts b/packages/background-removal/test/background-removal.test.ts
index 6cf98c83..0fd85326 100644
--- a/packages/background-removal/test/background-removal.test.ts
+++ b/packages/background-removal/test/background-removal.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { artifactTypes } from "@hypit/artifact";
import {
@@ -11,7 +11,7 @@ test("Background Removal is one image edge to one exact external Need", async ()
assert.deepEqual(backgroundRemovalFragment.inputs.map((input) => input.name), ["source"]);
assert.deepEqual(backgroundRemovalFragment.exports.map((output) => output.name), ["image"]);
assert.deepEqual(backgroundRemovalManifest.capabilities, [{ name: "remove-background", returns: artifactTypes.blob }]);
- const source = { kind: "blob" as const, digest: fixtureDigest("portrait"), size: 456, mediaType: "image/jpeg" };
+ const source = { kind: "blob" as const, resource: fixtureResource("portrait"), size: 456, mediaType: "image/jpeg" };
const result = await backgroundRemovalComponent.producers[0]!.handler({ inputs: { source: { value: source } } } as never);
assert.deepEqual(result.needs.image, { source });
assert.deepEqual(backgroundRemovalCapabilities.remove.module.version, "1");
diff --git a/packages/build-result-s3/README.md b/packages/build-result-s3/README.md
index e9af8398..7b592dd1 100644
--- a/packages/build-result-s3/README.md
+++ b/packages/build-result-s3/README.md
@@ -31,7 +31,7 @@ Objects keep the same visible shape as the filesystem repository:
values/...
```
-There is no global Build table or content-addressed Result namespace. A reused historical Output is a
+There is no global Build table or shared Result namespace. A reused historical Output is a
small forward reference to its producing Build and Output; following several such references still
reads the original file and does not upload another copy. While a Build is running, a private writer
file records only the state needed to continue publishing completed public Outputs and is removed when
diff --git a/packages/build-result-s3/src/repository.ts b/packages/build-result-s3/src/repository.ts
index cf077a61..695793ff 100644
--- a/packages/build-result-s3/src/repository.ts
+++ b/packages/build-result-s3/src/repository.ts
@@ -84,7 +84,7 @@ function scalar(value: unknown): value is null | boolean | number | string {
function isBlobRef(value: unknown): value is BlobRef {
if (value === null || Array.isArray(value) || typeof value !== "object") return false;
const item = value as Readonly<Record<string, unknown>>;
- return item.kind === "blob" && typeof item.digest === "string" && typeof item.size === "number" && typeof item.mediaType === "string";
+ return item.kind === "blob" && typeof item.resource === "string" && typeof item.size === "number" && typeof item.mediaType === "string";
}
function resourceIdentity(artifact: BlobRef): string {
@@ -158,7 +158,7 @@ class S3BuildResultWriter implements BuildResultWriter {
}
path = candidate;
resources.set(identity, path);
- const chunks = await input.artifacts.open(artifact);
+ const chunks = await input.resources.open(artifact);
if (chunks === undefined) throw new Error(`Build resource ${identity} is unavailable`);
await this.#repository.writeFile(this.#build, path, chunks, artifact.mediaType);
}
diff --git a/packages/build-result-s3/test/repository.test.ts b/packages/build-result-s3/test/repository.test.ts
index 41e5c47f..333e1069 100644
--- a/packages/build-result-s3/test/repository.test.ts
+++ b/packages/build-result-s3/test/repository.test.ts
@@ -83,7 +83,6 @@ test("S3 keeps the same Build Result model as the filesystem repository", async
const video: BlobRef = {
kind: "blob",
resource: "res_same_build_video",
- digest: `sha256:${"1".repeat(64)}`,
size: bytes.byteLength,
mediaType: "video/mp4",
};
@@ -124,7 +123,7 @@ test("S3 keeps the same Build Result model as the filesystem repository", async
},
],
}),
- artifacts: {
+ resources: {
async open() {
return (async function* () {
yield bytes;
@@ -181,7 +180,6 @@ test("S3 forwarding can cross several Builds without copying the historical file
value: {
kind: "blob",
resource: "res_original",
- digest: `sha256:${"2".repeat(64)}`,
size: bytes.byteLength,
mediaType: "video/mp4",
},
@@ -195,7 +193,7 @@ test("S3 forwarding can cross several Builds without copying the historical file
},
],
}),
- artifacts: {
+ resources: {
async open() {
return (async function* () {
yield bytes;
@@ -221,7 +219,7 @@ test("S3 forwarding can cross several Builds without copying the historical file
type: videoType,
value: {
kind: "blob",
- digest: `sha256:${"3".repeat(64)}`,
+ resource: "res_reused",
size: bytes.byteLength,
mediaType: "video/mp4",
},
@@ -235,7 +233,7 @@ test("S3 forwarding can cross several Builds without copying the historical file
},
],
}),
- artifacts: {
+ resources: {
async open() {
throw new Error("forwarded bytes must not be copied");
},
diff --git a/packages/build-result/src/store.ts b/packages/build-result/src/store.ts
index afa2558b..1a272a9a 100644
--- a/packages/build-result/src/store.ts
+++ b/packages/build-result/src/store.ts
@@ -16,7 +16,7 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import type { BlobRef, BuildState, StoredValue, TypedRecord } from "@hypit/protocol";
import type {
- BuildResultArtifactSource,
+ BuildResultResourceSource,
BuildResultFileRef,
BuildResultFinish,
BuildResultJsonValue,
@@ -63,7 +63,7 @@ function isBlobRef(value: unknown): value is BlobRef {
if (value === null || Array.isArray(value) || typeof value !== "object") return false;
const item = value as Readonly<Record<string, unknown>>;
return item.kind === "blob"
- && typeof item.digest === "string"
+ && typeof item.resource === "string"
&& typeof item.size === "number"
&& Number.isSafeInteger(item.size)
&& item.size >= 0
@@ -98,7 +98,7 @@ async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
}
async function copyArtifactAtomic(
- source: BuildResultArtifactSource,
+ source: BuildResultResourceSource,
artifact: BlobRef,
destination: string,
): Promise<void> {
@@ -388,7 +388,7 @@ export class FileBuildResult {
relativePath = candidate;
resources.set(identity, relativePath);
}
- await copyArtifactAtomic(input.artifacts, artifact, join(this.directory, relativePath));
+ await copyArtifactAtomic(input.resources, artifact, join(this.directory, relativePath));
return { kind: "build-file", path: relativePath, size: artifact.size, mediaType: artifact.mediaType };
};
const convert = async (value: unknown, preferredName: string): Promise<BuildResultJsonValue> => {
diff --git a/packages/build-result/src/types.ts b/packages/build-result/src/types.ts
index 0089eb32..4d728940 100644
--- a/packages/build-result/src/types.ts
+++ b/packages/build-result/src/types.ts
@@ -82,13 +82,13 @@ export type BuildResultSeed = {
readonly startedAt?: number;
};
-export type BuildResultArtifactSource = {
+export type BuildResultResourceSource = {
open(artifact: BlobRef): Promise<AsyncIterable<Uint8Array> | undefined>;
};
export type BuildResultSync = {
readonly state: BuildState;
- readonly artifacts: BuildResultArtifactSource;
+ readonly resources: BuildResultResourceSource;
};
export type BuildResultFinish = {
diff --git a/packages/build-result/test/result.test.ts b/packages/build-result/test/result.test.ts
index adcd997f..79e3c572 100644
--- a/packages/build-result/test/result.test.ts
+++ b/packages/build-result/test/result.test.ts
@@ -34,7 +34,6 @@ test("one same-Build resource backs a public video and a SemanticTake payload",
const video: BlobRef = {
kind: "blob",
resource: "res_same-build-video",
- digest: `sha256:${"1".repeat(64)}`,
size: bytes.byteLength,
mediaType: "video/mp4",
};
@@ -66,7 +65,7 @@ test("one same-Build resource backs a public video and a SemanticTake payload",
{ output: "logical:unused", candidate: "candidate:unused", record: "record:unused" },
],
}),
- artifacts: {
+ resources: {
async open(artifact) {
assert.equal(artifact.resource, video.resource);
return (async function* () { yield bytes; })();
@@ -117,14 +116,14 @@ test("an explicitly reused public output is a forward reference and copies no by
type: videoType,
value: {
kind: "blob",
- digest: `sha256:${"2".repeat(64)}`,
+ resource: "res_prior_video",
size: 10,
mediaType: "video/mp4",
},
}],
selections: [{ output: "logical:shot-video", candidate: "candidate:prior", record: "record:prior" }],
}),
- artifacts: {
+ resources: {
async open() {
throw new Error("a forwarded output must not copy its historical bytes");
},
diff --git a/packages/caption-fine/test/caption-fine.test.ts b/packages/caption-fine/test/caption-fine.test.ts
index 897b536d..cae31e6e 100644
--- a/packages/caption-fine/test/caption-fine.test.ts
+++ b/packages/caption-fine/test/caption-fine.test.ts
@@ -8,7 +8,7 @@ import { captionDocument, parseScript } from "@hypit/script";
import type { SpatialRegionTimeline } from "@hypit/spatial";
import type { SvsRecipe } from "@hypit/svs";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
fineCaptionParameters,
fineCaptionStyle,
@@ -19,7 +19,7 @@ import {
const font: FontArtifactRef = {
sources: [{ artifact: {
kind: "blob",
- digest: fixtureDigest("caption-fine-font"),
+ resource: fixtureResource("caption-fine-font"),
size: 1_024,
mediaType: "font/woff2",
} }],
diff --git a/packages/cli/src/archive.ts b/packages/cli/src/archive.ts
index bf1d3ce6..4af1bcbd 100644
--- a/packages/cli/src/archive.ts
+++ b/packages/cli/src/archive.ts
@@ -2,13 +2,13 @@ import { randomUUID } from "node:crypto";
import { mkdir, open, rename, rm, writeFile } from "node:fs/promises";
import { dirname } from "node:path";
-import type { CliRuntimeArtifactAccess } from "./runtime-port.js";
-import { isDigest } from "@hypit/protocol";
-import type { BuildState, Digest, TypedRecord, TypeRef } from "@hypit/protocol";
+import type { CliRuntimeResourceAccess } from "./runtime-port.js";
+import { isResourceId } from "@hypit/protocol";
+import type { BuildState, ResourceId, TypedRecord, TypeRef } from "@hypit/protocol";
import type { BuildCatalogEntry } from "@hypit/runtime";
type ArtifactIdentity = {
- readonly digest: Digest;
+ readonly resource: ResourceId;
readonly size: number;
readonly mediaType: string;
};
@@ -29,10 +29,10 @@ export type ArchivedLogicalOutput = {
function artifactIdentity(value: unknown): ArtifactIdentity | undefined {
if (value === null || Array.isArray(value) || typeof value !== "object") return undefined;
const candidate = value as Readonly<Record<string, unknown>>;
- if (typeof candidate.digest !== "string" || !isDigest(candidate.digest)
+ if (typeof candidate.resource !== "string" || !isResourceId(candidate.resource)
|| typeof candidate.size !== "number" || !Number.isSafeInteger(candidate.size) || candidate.size < 0
|| typeof candidate.mediaType !== "string" || candidate.mediaType.trim().length === 0) return undefined;
- return { digest: candidate.digest, size: candidate.size, mediaType: candidate.mediaType };
+ return { resource: candidate.resource, size: candidate.size, mediaType: candidate.mediaType };
}
function recordArtifact(record: TypedRecord): ArtifactIdentity | undefined {
@@ -41,11 +41,11 @@ function recordArtifact(record: TypedRecord): ArtifactIdentity | undefined {
}
export async function materializeRecord(
- runtime: Pick<CliRuntimeArtifactAccess, "openArtifact">,
+ runtime: Pick<CliRuntimeResourceAccess, "openResource">,
record: TypedRecord,
destination: string,
): Promise<
- | { readonly kind: "artifact"; readonly path: string; readonly digest: string; readonly size: number; readonly mediaType: string }
+ | { readonly kind: "artifact"; readonly path: string; readonly resource: string; readonly size: number; readonly mediaType: string }
| { readonly kind: "json"; readonly path: string; readonly size: number }
> {
await mkdir(dirname(destination), { recursive: true });
@@ -60,14 +60,14 @@ export async function materializeRecord(
}
export async function materializeArtifact(
- runtime: Pick<CliRuntimeArtifactAccess, "openArtifact">,
+ runtime: Pick<CliRuntimeResourceAccess, "openResource">,
artifact: ArtifactIdentity,
destination: string,
subject = "Build archive",
-): Promise<{ readonly kind: "artifact"; readonly path: string; readonly digest: string; readonly size: number; readonly mediaType: string }> {
+): Promise<{ readonly kind: "artifact"; readonly path: string; readonly resource: string; readonly size: number; readonly mediaType: string }> {
await mkdir(dirname(destination), { recursive: true });
- const source = await runtime.openArtifact(artifact.digest);
- if (source === undefined) throw new Error(`Artifact ${artifact.digest} is absent from the selected ArtifactStore`);
+ const source = await runtime.openResource(artifact.resource);
+ if (source === undefined) throw new Error(`Artifact ${artifact.resource} is absent from the selected ResourceStore`);
const temporary = `${destination}.hypit-${randomUUID()}.part`;
const output = await open(temporary, "wx");
let size = 0;
@@ -77,7 +77,7 @@ export async function materializeArtifact(
await output.write(chunk);
}
await output.close();
- if (size !== artifact.size) throw new Error(`Artifact ${artifact.digest} size differs from ${subject}`);
+ if (size !== artifact.size) throw new Error(`Artifact ${artifact.resource} size differs from ${subject}`);
// Replace an explicitly selected destination only after the stream completes.
await rename(temporary, destination);
} catch (error) {
@@ -94,7 +94,7 @@ export function collectArtifacts(
found: { path: string; artifact: ArtifactIdentity }[] = [],
): readonly {
readonly path: string;
- readonly digest: Digest;
+ readonly resource: ResourceId;
readonly size: number;
readonly mediaType: string;
}[] {
@@ -108,12 +108,12 @@ export function collectArtifacts(
return found.map((item) => ({ path: item.path, ...item.artifact }));
}
-export function findArchivedArtifact(state: BuildState, digest: string): readonly ArchivedArtifactReference[] {
- if (!isDigest(digest)) throw new Error(`--artifact requires a valid sha256 digest, received ${digest}`);
+export function findArchivedArtifact(state: BuildState, resource: string): readonly ArchivedArtifactReference[] {
+ if (!isResourceId(resource)) throw new Error(`--artifact requires a valid resource id, received ${resource}`);
return state.records.flatMap((record) => {
const value = record.value.kind === "blob" ? record.value : record.value.value;
return collectArtifacts(value)
- .filter((artifact) => artifact.digest === digest)
+ .filter((artifact) => artifact.resource === resource)
.map((artifact) => ({ record: record.id, ...artifact }));
});
}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
index 0103cde3..eea0b271 100644
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -9,7 +9,7 @@ export type { PinnedRecord } from "./archive.js";
export { runCli } from "./main.js";
export { discoverSourcePackages } from "./source-discovery.js";
export { loadDiscoveredSourcePackages } from "./source-packages.js";
-export { collectRunFrontends, loadRunFile } from "./run-file.js";
+export { collectRunFrontends, loadRunFile, resolveBuildResultRecord } from "./run-file.js";
export type { LoadedRunFile } from "./run-file.js";
export { hypitHostStateRoot, hypitProjectStateRoot } from "./paths.js";
export { findRuntimeProfile } from "./runtime-selection.js";
diff --git a/packages/cli/src/run-file.ts b/packages/cli/src/run-file.ts
index 432ae8b9..724642c6 100644
--- a/packages/cli/src/run-file.ts
+++ b/packages/cli/src/run-file.ts
@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
import type {
BuildResultRepository,
BuildResultFileRef,
@@ -38,131 +38,117 @@ export async function checkRunFile(options: {
return await compiler.checkSource(options.workspace.entry, options.workspace);
}
-function createRunCompiler(options: {
- readonly authorCompiler: NodeCompiler;
- readonly frontends: readonly RunFrontend[];
- readonly packageContributions: readonly NodePackageContribution[];
- readonly runtime?: Pick<CliRuntime, "status">;
- readonly results?: BuildResultRepository;
-}): NodeRunCompiler {
- const fragments = new RunFragmentRegistry();
- for (const item of options.packageContributions) {
- installRunFragmentHostFacets(item.hostFacets ?? [], fragments);
- }
- const frontends = new RunFrontendRegistry();
- for (const frontend of options.frontends) frontends.register(frontend);
- const archive = new Map<string, Awaited<ReturnType<CliRuntime["status"]>>>();
- const archived = async (id: string) => {
- const existing = archive.get(id);
- if (existing !== undefined) return existing;
- const status = await options.runtime!.status(id);
- archive.set(id, status);
- return status;
- };
- const isResultFile = (value: unknown): value is BuildResultFileRef => {
- if (value === null || Array.isArray(value) || typeof value !== "object") return false;
- const item = value as Readonly<Record<string, unknown>>;
- return item.kind === "build-file" && typeof item.path === "string"
- && typeof item.size === "number" && typeof item.mediaType === "string";
- };
- const isResultOutput = (value: unknown): value is {
- readonly kind: "build-output";
- readonly build: string;
- readonly output: string;
- } => {
- if (value === null || Array.isArray(value) || typeof value !== "object") return false;
- const item = value as Readonly<Record<string, unknown>>;
- return item.kind === "build-output" && typeof item.build === "string" && typeof item.output === "string";
- };
- const resultAttachment = async (
- repository: BuildResultRepository,
- owner: string,
- file: BuildResultFileRef,
- ): Promise<ArtifactAttachment> => {
- const build = file.build ?? owner;
- const initial = await repository.openFile(build, file);
- if (initial === undefined) throw new Error(`Build ${build} file ${file.path} is unavailable`);
- const hash = createHash("sha256");
- let size = 0;
- for await (const value of initial) {
- const chunk = Uint8Array.from(value);
- hash.update(chunk);
- size += chunk.byteLength;
- }
- if (size !== file.size) throw new Error(`Build ${build} file ${file.path} has size ${size}, expected ${file.size}`);
+function isResultFile(value: unknown): value is BuildResultFileRef {
+ if (value === null || Array.isArray(value) || typeof value !== "object") return false;
+ const item = value as Readonly<Record<string, unknown>>;
+ return item.kind === "build-file" && typeof item.path === "string"
+ && typeof item.size === "number" && typeof item.mediaType === "string";
+}
+
+function isResultOutput(value: unknown): value is {
+ readonly kind: "build-output";
+ readonly build: string;
+ readonly output: string;
+} {
+ if (value === null || Array.isArray(value) || typeof value !== "object") return false;
+ const item = value as Readonly<Record<string, unknown>>;
+ return item.kind === "build-output" && typeof item.build === "string" && typeof item.output === "string";
+}
+
+function isBlob(value: unknown): value is BlobRef {
+ if (value === null || Array.isArray(value) || typeof value !== "object") return false;
+ const item = value as Readonly<Record<string, unknown>>;
+ return item.kind === "blob" && typeof item.resource === "string"
+ && typeof item.size === "number" && typeof item.mediaType === "string";
+}
+
+/** Resolve one historical public Output into an ordinary Run value plus lazy file attachments. */
+export async function resolveBuildResultRecord(
+ repository: BuildResultRepository,
+ build: string,
+ output: string,
+): Promise<{
+ readonly type: RepositoryBuildResultOutput["type"];
+ readonly value: StoredValue;
+ readonly attachments?: readonly ArtifactAttachment[];
+} | undefined> {
+ const resultAttachment = async (owner: string, file: BuildResultFileRef): Promise<ArtifactAttachment> => {
+ const fileBuild = file.build ?? owner;
const artifact: BlobRef = {
kind: "blob",
resource: `res_${randomUUID()}`,
- digest: `sha256:${hash.digest("hex")}`,
- size,
+ size: file.size,
mediaType: file.mediaType,
- origin: { kind: "build-file", build, path: file.path },
+ origin: { kind: "build-file", build: fileBuild, path: file.path },
};
return {
artifact,
async open() {
- const stream = await repository.openFile(build, file);
- if (stream === undefined) throw new Error(`Build ${build} file ${file.path} is unavailable`);
+ const stream = await repository.openFile(fileBuild, file);
+ if (stream === undefined) throw new Error(`Build ${fileBuild} file ${file.path} is unavailable`);
return stream;
},
};
};
- const isBlob = (value: unknown): value is BlobRef => {
- if (value === null || Array.isArray(value) || typeof value !== "object") return false;
- const item = value as Readonly<Record<string, unknown>>;
- return item.kind === "blob" && typeof item.digest === "string"
- && typeof item.size === "number" && typeof item.mediaType === "string";
- };
+ const attachments: ArtifactAttachment[] = [];
const resultValue = async (
value: BuildResultJsonValue,
owner: string,
- attachments: ArtifactAttachment[],
): Promise<CanonicalValue | BlobRef> => {
- const repository = options.results;
- if (repository === undefined) throw new Error("Build Result resolution has no Repository");
if (isResultFile(value)) {
- const attachment = await resultAttachment(repository, owner, value);
+ const attachment = await resultAttachment(owner, value);
attachments.push(attachment);
return attachment.artifact;
}
if (isResultOutput(value)) {
const forwarded = await repository.resolve(value.build, value.output);
if (forwarded === undefined) throw new Error(`Build ${value.build} has no Output ${value.output}`);
- return await resolvedValue(forwarded, attachments);
+ return await resolvedValue(forwarded);
}
if (Array.isArray(value)) {
- return await Promise.all(value.map(async (item) => await resultValue(item, owner, attachments))) as CanonicalValue;
+ return await Promise.all(value.map(async (item) => await resultValue(item, owner))) as CanonicalValue;
}
if (value !== null && typeof value === "object") {
return Object.fromEntries(await Promise.all(Object.entries(value)
- .map(async ([key, item]) => [key, await resultValue(item, owner, attachments)] as const))) as CanonicalValue;
+ .map(async ([key, item]) => [key, await resultValue(item, owner)] as const))) as CanonicalValue;
}
return value;
};
- const resolvedValue = async (
- resolved: RepositoryBuildResultOutput,
- attachments: ArtifactAttachment[],
- ): Promise<BlobRef | CanonicalValue> => {
- if (resolved.value.kind === "build-file") return await resultValue(resolved.value, resolved.build, attachments);
+ const resolvedValue = async (resolved: RepositoryBuildResultOutput): Promise<BlobRef | CanonicalValue> => {
+ if (resolved.value.kind === "build-file") return await resultValue(resolved.value, resolved.build);
if (resolved.value.kind === "inline") return resolved.value.value;
- return await resultValue(resolved.value.value, resolved.build, attachments);
+ return await resultValue(resolved.value.value, resolved.build);
};
- const storedResult = async (build: string, output: string): Promise<{
- readonly type: RepositoryBuildResultOutput["type"];
- readonly value: StoredValue;
- readonly attachments?: readonly ArtifactAttachment[];
- } | undefined> => {
- const repository = options.results;
- if (repository === undefined) return undefined;
- const resolved = await repository.resolve(build, output);
- if (resolved === undefined) return undefined;
- const attachments: ArtifactAttachment[] = [];
- const value = await resolvedValue(resolved, attachments);
- return {
- type: resolved.type,
- value: isBlob(value) ? value : { kind: "inline", value },
- ...(attachments.length === 0 ? {} : { attachments }),
- };
+ const resolved = await repository.resolve(build, output);
+ if (resolved === undefined) return undefined;
+ const value = await resolvedValue(resolved);
+ return {
+ type: resolved.type,
+ value: isBlob(value) ? value : { kind: "inline", value },
+ ...(attachments.length === 0 ? {} : { attachments }),
+ };
+}
+
+function createRunCompiler(options: {
+ readonly authorCompiler: NodeCompiler;
+ readonly frontends: readonly RunFrontend[];
+ readonly packageContributions: readonly NodePackageContribution[];
+ readonly runtime?: Pick<CliRuntime, "status">;
+ readonly results?: BuildResultRepository;
+}): NodeRunCompiler {
+ const fragments = new RunFragmentRegistry();
+ for (const item of options.packageContributions) {
+ installRunFragmentHostFacets(item.hostFacets ?? [], fragments);
+ }
+ const frontends = new RunFrontendRegistry();
+ for (const frontend of options.frontends) frontends.register(frontend);
+ const archive = new Map<string, Awaited<ReturnType<CliRuntime["status"]>>>();
+ const archived = async (id: string) => {
+ const existing = archive.get(id);
+ if (existing !== undefined) return existing;
+ const status = await options.runtime!.status(id);
+ archive.set(id, status);
+ return status;
};
return new NodeRunCompiler({
authorCompiler: options.authorCompiler,
@@ -170,7 +156,7 @@ function createRunCompiler(options: {
fragments,
...(options.results !== undefined ? {
async resolveBuildRecord(id: string, output: string) {
- return await storedResult(id, output);
+ return await resolveBuildResultRecord(options.results!, id, output);
},
} : options.runtime === undefined ? {} : {
async resolveBuildRecord(id: string, output: string) {
diff --git a/packages/cli/src/runtime-port.ts b/packages/cli/src/runtime-port.ts
index 97d99d77..7226d772 100644
--- a/packages/cli/src/runtime-port.ts
+++ b/packages/cli/src/runtime-port.ts
@@ -3,7 +3,7 @@ export type {
ManagedProgramReport as CliManagedProgramReport,
RuntimeController as CliRuntimeController,
RuntimeHostArchive as CliRuntimeArchiveControl,
- RuntimeHostArtifactAccess as CliRuntimeArtifactAccess,
+ RuntimeHostResourceAccess as CliRuntimeResourceAccess,
RuntimeHostBuildSubmission as CliBuildSubmission,
RuntimeHostCredentialControl as CliCredentialControl,
RuntimeHostCredentialStatus as CliCredentialStatus,
diff --git a/packages/cli/test/build-results.test.ts b/packages/cli/test/build-results.test.ts
index 71df18a8..b72d7b10 100644
--- a/packages/cli/test/build-results.test.ts
+++ b/packages/cli/test/build-results.test.ts
@@ -42,7 +42,7 @@ async function fixture(root: string): Promise<void> {
});
await result.sync({
state: completedState(),
- artifacts: { async open() { throw new Error("inline Result has no files"); } },
+ resources: { async open() { throw new Error("inline Result has no files"); } },
});
}
@@ -182,15 +182,14 @@ test("build-record reads one exact result file and preserves its historical orig
type: videoType,
value: {
kind: "blob",
- resource: "resource:prior-video",
- digest: "runtime-address:prior-video",
+ resource: "res_prior_video",
size: bytes.byteLength,
mediaType: "video/mp4",
},
}],
plan: { selections: [{ output: "logical:video", candidate: "candidate:video", record: "record:video" }] },
} as unknown as BuildState,
- artifacts: {
+ resources: {
async open() {
return (async function* () { yield bytes; })();
},
@@ -213,12 +212,19 @@ test("build-record reads one exact result file and preserves its historical orig
</svrun>`, "utf8");
const workspace = await authorCompiler.openFile(runFile);
+ const repository = new FileBuildResultRepository(resultsRoot);
+ let opens = 0;
+ const countedRepository: FileBuildResultRepository = Object.create(repository) as FileBuildResultRepository;
+ countedRepository.openFile = async (build, file) => {
+ opens += 1;
+ return await repository.openFile(build, file);
+ };
const loaded = await loadRunFile({
workspace,
authorCompiler,
frontends: [runMarkupFrontend],
packageContributions: [],
- results: new FileBuildResultRepository(resultsRoot),
+ results: countedRepository,
});
const candidate = loaded.run.graph.candidates[0];
assert.equal(candidate?.root.kind, "value");
@@ -230,6 +236,11 @@ test("build-record reads one exact result file and preserves its historical orig
path: "files/shot.video.mp4",
});
assert.equal(loaded.attachments.length, 1);
+ assert.equal(opens, 0, "compilation does not read or summarize historical bytes");
+ const reused: number[] = [];
+ for await (const chunk of await loaded.attachments[0]!.open()) reused.push(...chunk);
+ assert.deepEqual(Uint8Array.from(reused), bytes);
+ assert.equal(opens, 1, "Runtime staging opens the historical Result exactly once");
assert.equal(loaded.compiler.planCompilation(loaded).state.plan.steps.length, 0);
} finally {
await rm(root, { recursive: true, force: true });
diff --git a/packages/cli/test/control-commands.test.ts b/packages/cli/test/control-commands.test.ts
index d50cf061..c73a3f2f 100644
--- a/packages/cli/test/control-commands.test.ts
+++ b/packages/cli/test/control-commands.test.ts
@@ -58,7 +58,7 @@ test("queue opens durable control without constructing execution Providers", asy
test("status --watch reattaches to one durable Build until it becomes terminal", async () => {
const calls: string[] = [];
const state = {
- id: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+ id: "build-watch-state",
status: "active",
diagnostics: [],
};
diff --git a/packages/cli/test/output.test.ts b/packages/cli/test/output.test.ts
index cf605062..7461f966 100644
--- a/packages/cli/test/output.test.ts
+++ b/packages/cli/test/output.test.ts
@@ -6,7 +6,7 @@ import type { BuildPlan } from "@hypit/protocol";
import { renderCliError, writeCliHelp, writeCliOutput } from "../src/output.js";
import type { PlanPreflight } from "../src/output.js";
-const digest = `sha256:${"1".repeat(64)}` as const;
+const resource = "res_cli-output" as const;
function capture(
options: Parameters<typeof writeCliOutput>[1],
@@ -33,7 +33,7 @@ test("author check renders a compact human summary without dumping identity", ()
sourceKind: "author",
ok: true,
units: 2,
- sourceAssets: [{ digest }],
+ sourceAssets: [{ resource }],
modules: ["@hypit/script@1"],
exports: [{
name: "story",
@@ -45,7 +45,7 @@ test("author check renders a compact human summary without dumping identity", ()
assert.match(output, /✓ Source is valid/u);
assert.match(output, /Frontend\s+@hypit\/markup@1/u);
assert.match(output, /story\s+@hypit\/narrative@1\/Narrative/u);
- assert.doesNotMatch(output, /sha256:/u);
+ assert.doesNotMatch(output, /res_cli-output/u);
assert.doesNotMatch(output, /\u001b\[/u);
});
diff --git a/packages/comment-sticker-studio/src/index.ts b/packages/comment-sticker-studio/src/index.ts
index 7f6e9792..85676973 100644
--- a/packages/comment-sticker-studio/src/index.ts
+++ b/packages/comment-sticker-studio/src/index.ts
@@ -88,7 +88,7 @@ function projectComments(context: StudioTrackCompanionContext): readonly StudioE
display: {
title: entity.display.title,
layers: [
- ...(item.avatar === undefined ? [] : [previewLayer(artifactPreview("image", item.avatar.digest), "contain", "decoration")]),
+ ...(item.avatar === undefined ? [] : [previewLayer(artifactPreview("image", item.avatar.resource), "contain", "decoration")]),
textLayer(item.content.comment),
],
},
diff --git a/packages/comment-sticker/src/manifest.ts b/packages/comment-sticker/src/manifest.ts
index 911b9d7d..b8d83abb 100644
--- a/packages/comment-sticker/src/manifest.ts
+++ b/packages/comment-sticker/src/manifest.ts
@@ -53,7 +53,7 @@ const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema;
const enumString = (values: readonly string[]): ValueSchema => ({ kind: "string", enum: values });
const blobRef = object({
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
size: { schema: unsignedInteger },
mediaType: { schema: string },
});
diff --git a/packages/comment-sticker/src/program.ts b/packages/comment-sticker/src/program.ts
index f26cd570..b44b458a 100644
--- a/packages/comment-sticker/src/program.ts
+++ b/packages/comment-sticker/src/program.ts
@@ -13,7 +13,7 @@ import type {
import { assertFontArtifactRef } from "@hypit/media";
import { assertProgramSpaceIdentity } from "@hypit/program-space";
import type { ProgramSpace } from "@hypit/program-space";
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
@@ -161,7 +161,7 @@ export function setCommentStickerContentText(
}
function assertAvatar(value: BlobRef): void {
- assert(value.kind === "blob" && isDigest(value.digest), "Comment Sticker avatar is not a BlobRef.");
+ assert(value.kind === "blob" && isResourceId(value.resource), "Comment Sticker avatar is not a BlobRef.");
integer(value.size, "Comment Sticker avatar size");
assert(value.mediaType.startsWith("image/"), "Comment Sticker avatar must be an image Artifact.");
}
diff --git a/packages/comment-sticker/test/comment-sticker.test.ts b/packages/comment-sticker/test/comment-sticker.test.ts
index 08343d2c..fd9eae00 100644
--- a/packages/comment-sticker/test/comment-sticker.test.ts
+++ b/packages/comment-sticker/test/comment-sticker.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import { projectProgramWindow } from "../../../test/temporal-fixture.js";
@@ -36,7 +36,7 @@ import {
} from "../src/index.js";
const font: FontArtifactRef = {
- sources: [{ artifact: { kind: "blob", digest: fixtureDigest("comment-sticker-font"), size: 1_024, mediaType: "font/woff2" } }],
+ sources: [{ artifact: { kind: "blob", resource: fixtureResource("comment-sticker-font"), size: 1_024, mediaType: "font/woff2" } }],
weight: 800,
style: "normal",
};
@@ -167,7 +167,7 @@ test("Style Surface consumes an explicit SVS Recipe and exact Font Stack", async
});
test("Track Surface lowers mixed program and semantic Stickers to a finite explicit graph", async () => {
- const blob = { kind: "blob" as const, digest: fixtureDigest("comment-avatar"), size: 128, mediaType: "image/png" };
+ const blob = { kind: "blob" as const, resource: fixtureResource("comment-avatar"), size: 128, mediaType: "image/png" };
const refs = new Map<string, SurfaceResolvedReference>([
["video.canvas", authored("video.canvas", spatialTypes.canvas, canvas)],
["video.semantic", authored("video.semantic", semanticTrackTypes.track, semantic)],
diff --git a/packages/compiler-node/README.md b/packages/compiler-node/README.md
index 2842b264..7aa2d744 100644
--- a/packages/compiler-node/README.md
+++ b/packages/compiler-node/README.md
@@ -17,7 +17,7 @@ The compiler has no suffix table and no entry-Frontend default. A recursively im
select another Frontend without the importer choosing on its behalf.
`ModulePackageRegistry` maps author import spellings to exact, already trusted manifests and closes
-their digest-bound dependencies. It does not install npm packages or execute module code. An
+their declared Resource dependencies. It does not install npm packages or execute module code. An
embedding application must register the manifests and matching Frontend/Surface implementations it
has chosen to trust.
@@ -31,8 +31,8 @@ The Workspace session owns a separate Source Asset capability. A Frontend/Surfac
asset and assign its exact media type, but it never receives a path, filesystem handle or ambient
read authority. The Workspace returns a `BlobRef`, the compiler binds that reference into the
requesting SourceUnit, and the session exposes defensive generic `ArtifactAttachment`s on the Node
-compilation result. `check` and `plan` perform no ArtifactStore write. `build` passes the attachments
-to the selected Runtime for digest-checked staging.
+compilation result. `check` and `plan` perform no ResourceStore write. `build` passes the attachments
+to the selected Runtime for size-checked staging.
SourceUnit recursion and Source Asset resolution are intentionally different capabilities: an
asset cannot import syntax, and a source import does not silently make arbitrary neighboring bytes
diff --git a/packages/compiler-node/src/compiler.ts b/packages/compiler-node/src/compiler.ts
index d77a18ef..11eb081a 100644
--- a/packages/compiler-node/src/compiler.ts
+++ b/packages/compiler-node/src/compiler.ts
@@ -1,4 +1,4 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
import {
compileSourceClosure,
@@ -30,7 +30,7 @@ type DiscoveredUnit = {
};
function attachmentKey(artifact: BlobRef): string {
- return `${artifact.digest}\u0000${artifact.mediaType}`;
+ return `${artifact.resource}\u0000${artifact.mediaType}`;
}
export function mergeAttachments(groups: readonly (readonly ArtifactAttachment[])[]): readonly ArtifactAttachment[] {
@@ -42,8 +42,8 @@ export function mergeAttachments(groups: readonly (readonly ArtifactAttachment[]
if (existing.artifact.size !== item.artifact.size) {
throw new NodeCompilerError(
"SOURCE_ATTACHMENT_CONFLICT",
- `Artifact attachment ${item.artifact.digest} carries conflicting sizes`,
- item.artifact.digest,
+ `Artifact attachment ${item.artifact.resource} carries conflicting sizes`,
+ item.artifact.resource,
);
}
continue;
@@ -163,7 +163,6 @@ export class NodeCompiler {
const artifact: BlobRef = {
kind: "blob",
resource: `res_${randomUUID()}`,
- digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
size: bytes.byteLength,
mediaType: request.mediaType,
};
@@ -172,7 +171,7 @@ export class NodeCompiler {
if (existing !== undefined && existing.artifact.size !== bytes.byteLength) {
throw new NodeCompilerError(
"SOURCE_ATTACHMENT_CONFLICT",
- `Embedded asset ${request.from} conflicts with ${artifact.digest}`,
+ `Embedded asset ${request.from} conflicts with ${artifact.resource}`,
request.from,
);
}
diff --git a/packages/compiler-node/src/run.ts b/packages/compiler-node/src/run.ts
index 429c915e..1799c8b7 100644
--- a/packages/compiler-node/src/run.ts
+++ b/packages/compiler-node/src/run.ts
@@ -156,7 +156,7 @@ async function storedValueFromWorkspace(
from: string,
): Promise<StoredValue> {
const resolved = await workspace.resolveAsset(source, { from, mediaType: "application/json" });
- const attachment = (await workspace.attachments()).find((item) => item.artifact.digest === resolved.artifact.digest);
+ const attachment = (await workspace.attachments()).find((item) => item.artifact.resource === resolved.artifact.resource);
if (attachment === undefined) throw new Error(`Workspace did not retain bytes for ${from}`);
return decodeStoredValue(await attachmentBytes(attachment), from);
}
diff --git a/packages/compiler-node/test/compiler.test.ts b/packages/compiler-node/test/compiler.test.ts
index 67f8de51..ba1df4cb 100644
--- a/packages/compiler-node/test/compiler.test.ts
+++ b/packages/compiler-node/test/compiler.test.ts
@@ -1,5 +1,4 @@
import assert from "node:assert/strict";
-import { createHash } from "node:crypto";
import {
mkdtemp,
mkdir,
@@ -288,7 +287,6 @@ function memoryWorkspace(sourceText: string, assetBytes: Uint8Array): Workspace
const artifact: BlobRef = {
kind: "blob",
resource: "res_memory-reference",
- digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
size: bytes.byteLength,
mediaType: request.mediaType,
};
@@ -463,10 +461,10 @@ test("source assets become graph values and a Host transfer bundle without closu
const attachment = first.attachments[0];
assert.deepEqual(await readAttachment(attachment), new Uint8Array([1, 2, 3, 4]));
assert.equal(first.program.records[0]?.value.kind, "blob");
- assert.equal(first.program.records[0]?.value.kind === "blob" ? first.program.records[0].value.digest : undefined, attachment?.artifact.digest);
+ assert.equal(first.program.records[0]?.value.kind === "blob" ? first.program.records[0].value.resource : undefined, attachment?.artifact.resource);
await writeFile(asset, new Uint8Array([9, 8, 7]));
const second = await assetCompiler({ root }).compileFile(file);
- assert.notEqual(second.attachments[0]?.artifact.digest, attachment?.artifact.digest);
+ assert.notEqual(second.attachments[0]?.artifact.resource, attachment?.artifact.resource);
});
test("an installed package Surface can contribute embedded bytes without an author file or network", async () => {
@@ -483,8 +481,8 @@ test("an installed package Surface can contribute embedded bytes without an auth
assert.deepEqual(await readAttachment(attachment), new Uint8Array([8, 6, 7, 5, 3, 0, 9]));
assert.equal(compiled.program.records[0]?.value.kind, "blob");
assert.equal(compiled.program.records[0]?.value.kind === "blob"
- ? compiled.program.records[0].value.digest
- : undefined, attachment?.artifact.digest);
+ ? compiled.program.records[0].value.resource
+ : undefined, attachment?.artifact.resource);
});
test("Run compilation retains embedded Author attachments for later Runtime staging", async () => {
@@ -548,7 +546,7 @@ test("filesystem Workspace captures source text and asset identity once", async
const detached = await workspace.attachments();
assert.deepEqual(await readAttachment(detached[0]), new Uint8Array([4, 5, 6, 7]),
"attachment bytes are opened lazily; Runtime rejects them if they no longer match the captured identity");
- assert.equal((await workspace.attachments())[0]?.artifact.digest, firstAsset.artifact.digest);
+ assert.equal((await workspace.attachments())[0]?.artifact.resource, firstAsset.artifact.resource);
await assert.rejects(
async () => await workspace.resolveSource(entry, {
from: "./escaped.svs",
@@ -610,8 +608,8 @@ test("filesystem and in-memory Workspaces load identical asset bytes", async ()
assert.notEqual(memoryArtifact.resource, filesystemArtifact.resource,
"separate admissions keep separate resource identities even for equal bytes");
assert.deepEqual(
- { digest: memoryArtifact.digest, size: memoryArtifact.size, mediaType: memoryArtifact.mediaType },
- { digest: filesystemArtifact.digest, size: filesystemArtifact.size, mediaType: filesystemArtifact.mediaType },
+ { size: memoryArtifact.size, mediaType: memoryArtifact.mediaType },
+ { size: filesystemArtifact.size, mediaType: filesystemArtifact.mediaType },
);
assert.deepEqual(await readAttachment(memory.attachments[0]),
await readAttachment(filesystem.attachments[0]));
diff --git a/packages/component-kit/README.md b/packages/component-kit/README.md
index f9103222..b84925f7 100644
--- a/packages/component-kit/README.md
+++ b/packages/component-kit/README.md
@@ -6,7 +6,7 @@ reference plus handler. Hosts enumerate them without running an opaque `install(
Producer handlers receive only the
Core command, Producer identity and immutable typed inputs.
-They receive no ArtifactStore, credentials, network client, queue or Runtime infrastructure. Work that
+They receive no ResourceStore, credentials, network client, queue or Runtime infrastructure. Work that
needs those authorities must emit an explicit Need and be implemented by a separately selected
Endpoint package. `@hypit/driver-node` implements the structural registrar but is not part of this
SDK.
diff --git a/packages/composition/src/schema.ts b/packages/composition/src/schema.ts
index 7beb0cae..1bd95c95 100644
--- a/packages/composition/src/schema.ts
+++ b/packages/composition/src/schema.ts
@@ -11,13 +11,13 @@ const object = (
): ValueSchema => ({ kind: "object", fields, ...(allowUnknown ? { allowUnknown: true } : {}) });
const audioBlobRef = object({
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
size: { schema: integer },
mediaType: { schema: { kind: "literal", value: "audio/wav" } },
});
const mediaBlobRef = object({
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
size: { schema: integer },
mediaType: { schema: string },
});
diff --git a/packages/composition/src/track.ts b/packages/composition/src/track.ts
index 6a0ff0f6..11f139ad 100644
--- a/packages/composition/src/track.ts
+++ b/packages/composition/src/track.ts
@@ -1,4 +1,4 @@
-import { canonicalStringify, isDigest } from "@hypit/protocol";
+import { canonicalStringify, isResourceId } from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
import {
@@ -459,7 +459,7 @@ function assertFrameSpan(span: FrameSpan, totalFrames: number, label: string): v
function assertMediaArtifact(artifact: BlobRef, label: string): void {
if (
artifact.kind !== "blob"
- || !isDigest(artifact.digest)
+ || !isResourceId(artifact.resource)
|| !Number.isSafeInteger(artifact.size)
|| artifact.size < 0
|| !artifact.mediaType
@@ -527,7 +527,7 @@ function assertSampling(value: VisualTimedSampling, durationFrames: number, labe
function assertAudioArtifact(artifact: BlobRef, label: string): void {
if (
artifact.kind !== "blob"
- || !isDigest(artifact.digest)
+ || !isResourceId(artifact.resource)
|| !Number.isSafeInteger(artifact.size)
|| artifact.size < 0
|| artifact.mediaType !== "audio/wav"
diff --git a/packages/composition/test/render.test.ts b/packages/composition/test/render.test.ts
index 512df152..39b90647 100644
--- a/packages/composition/test/render.test.ts
+++ b/packages/composition/test/render.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
assertCompositableSurfaceRef,
@@ -23,7 +23,7 @@ const space = sealProgramSpace({ id: "test-space", narrativeId: "test-narrative"
const font: FontArtifactRef = {
sources: [{ artifact: {
kind: "blob",
- digest: fixtureDigest("font:inter-bold"),
+ resource: fixtureResource("font:inter-bold"),
size: 1_024,
mediaType: "font/woff2",
} }],
@@ -34,7 +34,7 @@ const font: FontArtifactRef = {
const animatedSurface: CompositableSurfaceRef = {
artifact: {
kind: "blob",
- digest: fixtureDigest("surface:alpha-webm"),
+ resource: fixtureResource("surface:alpha-webm"),
size: 2_048,
mediaType: "video/webm",
},
@@ -49,7 +49,7 @@ const animatedSurface: CompositableSurfaceRef = {
},
};
-test("FontArtifactRef binds one exact font face to a content-addressed Blob", () => {
+test("FontArtifactRef binds one exact font face to a Resource Blob", () => {
assert.doesNotThrow(() => assertFontArtifactRef(font));
assert.throws(
() => assertFontArtifactRef({
diff --git a/packages/composition/test/track.test.ts b/packages/composition/test/track.test.ts
index 8753b467..e9ae21e4 100644
--- a/packages/composition/test/track.test.ts
+++ b/packages/composition/test/track.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { registerTypeValidatorFacets } from "@hypit/component-kit";
import { createResolvedClosure } from "@hypit/core";
@@ -34,13 +34,13 @@ const videoContractManifests = [artifactManifest, narrativeManifest, mediaManife
speechManifest, speechEvidenceManifest, svsManifest, spatialManifest, visualIrManifest, compositionManifest] as const;
const font: FontArtifactRef = {
- sources: [{ artifact: { kind: "blob", digest: fixtureDigest("track:test-font"), size: 1_024, mediaType: "font/woff2" } }],
+ sources: [{ artifact: { kind: "blob", resource: fixtureResource("track:test-font"), size: 1_024, mediaType: "font/woff2" } }],
weight: 700,
style: "normal",
};
const audio: BlobRef = {
kind: "blob",
- digest: fixtureDigest("audio"),
+ resource: fixtureResource("audio"),
size: 24,
mediaType: "audio/wav",
};
diff --git a/packages/core/src/graph.ts b/packages/core/src/graph.ts
index a29c6b50..1970cc7f 100644
--- a/packages/core/src/graph.ts
+++ b/packages/core/src/graph.ts
@@ -57,9 +57,8 @@ function normalizedStoredValue(value: StoredValue): StoredValue {
if (value.kind === "inline") return { kind: "inline", value: canonicalize(value.value) };
return {
kind: "blob",
- ...(value.resource === undefined ? {} : { resource: value.resource }),
...(value.origin === undefined ? {} : { origin: { ...value.origin } }),
- digest: value.digest,
+ resource: value.resource,
size: value.size,
mediaType: value.mediaType,
};
diff --git a/packages/deck-track/test/deck-track.test.ts b/packages/deck-track/test/deck-track.test.ts
index eee345f0..db282e0f 100644
--- a/packages/deck-track/test/deck-track.test.ts
+++ b/packages/deck-track/test/deck-track.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
import { videoContractManifests } from "../../../test/support/video-domain.js";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import { compositionDependency, compositionTypes } from "@hypit/composition";
@@ -77,13 +77,13 @@ const frame = sealSpatialFrame({
const image = (name: string) => ({
kind: "blob" as const,
- digest: fixtureDigest(`deck-image:${name}`),
+ resource: fixtureResource(`deck-image:${name}`),
size: 16,
mediaType: "image/png",
});
const video = (name: string) => ({
kind: "blob" as const,
- digest: fixtureDigest(`deck-video:${name}`),
+ resource: fixtureResource(`deck-video:${name}`),
size: 32,
mediaType: "video/mp4",
});
@@ -365,7 +365,7 @@ test("continue uses one explicit loop-start clock and past hide removes the reta
});
const font: FontArtifactRef = {
- sources: [{ artifact: { kind: "blob", digest: fixtureDigest("deck-font"), size: 64, mediaType: "font/woff2" } }],
+ sources: [{ artifact: { kind: "blob", resource: fixtureResource("deck-font"), size: 64, mediaType: "font/woff2" } }],
weight: 700,
style: "normal",
};
@@ -397,7 +397,7 @@ test("optional labels preserve exact fonts and remain inside the Card-owned pose
const label = element(track, "card-1:stage:1", (value) => value.kind === "text-flow");
assert.equal(label.kind, "text-flow");
assert.equal(label.parent, "deck-material:frame");
- assert.equal(label.typography.fonts?.[0]?.sources[0]?.artifact.digest, font.sources[0]!.artifact.digest);
+ assert.equal(label.typography.fonts?.[0]?.sources[0]?.artifact.resource, font.sources[0]!.artifact.resource);
const authored = exactLabel();
assert.equal(authored.kind, "text");
assert.throws(() => sealDepthStackCardLabel({
diff --git a/packages/driver-node/src/artifacts.ts b/packages/driver-node/src/artifacts.ts
deleted file mode 100644
index 0865be73..00000000
--- a/packages/driver-node/src/artifacts.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-
-import type { BlobRef, Digest } from "@hypit/protocol";
-
-import type { ArtifactStore } from "@hypit/runtime";
-
-export class MemoryArtifactStore implements ArtifactStore {
- readonly #values = new Map<Digest, Uint8Array>();
-
- async put(bytes: Uint8Array, mediaType: string): Promise<BlobRef> {
- const copy = Uint8Array.from(bytes);
- const digest = `sha256:${createHash("sha256").update(copy).digest("hex")}` as Digest;
- this.#values.set(digest, copy);
- return { kind: "blob", resource: `res_${randomUUID()}`, digest, size: copy.byteLength, mediaType };
- }
-
- async get(digest: Digest): Promise<Uint8Array | undefined> {
- const value = this.#values.get(digest);
- return value === undefined ? undefined : Uint8Array.from(value);
- }
-
- async has(digest: Digest): Promise<boolean> {
- return this.#values.has(digest);
- }
-}
diff --git a/packages/driver-node/src/driver.ts b/packages/driver-node/src/driver.ts
index b3b64cf7..60c37ba4 100644
--- a/packages/driver-node/src/driver.ts
+++ b/packages/driver-node/src/driver.ts
@@ -17,7 +17,7 @@ import {
} from "@hypit/validation";
import type { TypeValidatorRegistryLike } from "@hypit/validation";
import type {
- ArtifactStore,
+ ResourceStore,
CredentialStore,
CredentialValue,
OperationSnapshot,
@@ -29,7 +29,7 @@ import type {
RuntimeRunnableCommand,
} from "@hypit/runtime";
-import { MemoryArtifactStore } from "./artifacts.js";
+import { MemoryResourceStore } from "./resources.js";
import {
ProducerRegistry,
EndpointRegistry,
@@ -47,9 +47,9 @@ import type {
export type NodeDriverOptions = {
readonly producers?: ProducerRegistry;
readonly endpoints?: EndpointRegistry;
- readonly artifacts?: ArtifactStore;
+ readonly resources?: ResourceStore;
/** Runtime execution may isolate transient bytes by Build without exposing that policy to Endpoints. */
- readonly artifactsForBuild?: (build: string) => ArtifactStore;
+ readonly resourcesForBuild?: (build: string) => ResourceStore;
readonly operations?: OperationStore;
readonly credentials?: CredentialStore;
readonly validators?: TypeValidatorRegistryLike;
@@ -90,8 +90,8 @@ function failureMessage(error: unknown): string {
export class NodeDriver {
readonly producers: ProducerRegistry;
readonly endpoints: EndpointRegistry;
- readonly artifacts: ArtifactStore;
- readonly #artifactsForBuild: ((build: string) => ArtifactStore) | undefined;
+ readonly resources: ResourceStore;
+ readonly #resourcesForBuild: ((build: string) => ResourceStore) | undefined;
readonly operations: OperationStore | undefined;
readonly credentials: CredentialStore | undefined;
readonly validators: TypeValidatorRegistryLike;
@@ -99,15 +99,15 @@ export class NodeDriver {
constructor(options: NodeDriverOptions = {}) {
this.producers = options.producers ?? new ProducerRegistry();
this.endpoints = options.endpoints ?? new EndpointRegistry();
- this.artifacts = options.artifacts ?? new MemoryArtifactStore();
- this.#artifactsForBuild = options.artifactsForBuild;
+ this.resources = options.resources ?? new MemoryResourceStore();
+ this.#resourcesForBuild = options.resourcesForBuild;
this.operations = options.operations;
this.credentials = options.credentials;
this.validators = options.validators ?? new TypeValidatorRegistry();
}
- #artifactStore(build?: string): ArtifactStore {
- return build === undefined ? this.artifacts : this.#artifactsForBuild?.(build) ?? this.artifacts;
+ #resourceStore(build?: string): ResourceStore {
+ return build === undefined ? this.resources : this.#resourcesForBuild?.(build) ?? this.resources;
}
async #endpointCredentials(
@@ -325,7 +325,7 @@ export class NodeDriver {
const endpointContext = {
command: structuredClone(executable.command),
need: structuredClone(executable.command.need),
- artifacts: this.#artifactStore(context.build),
+ resources: this.#resourceStore(context.build),
credentials: await this.#endpointCredentials(executable.registration),
operation: identity.id,
};
@@ -428,7 +428,7 @@ export class NodeDriver {
const result = await executable.registration.handler({
command: structuredClone(executable.command),
need: structuredClone(executable.command.need),
- artifacts: this.#artifactStore(context?.build),
+ resources: this.#resourceStore(context?.build),
credentials: await this.#endpointCredentials(executable.registration),
});
return { status: "completed", event: await this.#endpointEvent(state, executable, result) };
@@ -501,7 +501,7 @@ export class NodeDriver {
const endpointContext = {
command: structuredClone(executable.command),
need: structuredClone(executable.command.need),
- artifacts: this.#artifactStore(operation.build),
+ resources: this.#resourceStore(operation.build),
credentials: await this.#endpointCredentials(executable.registration),
operation: current.id,
handle: structuredClone(current.handle as NonNullable<typeof current.handle>),
diff --git a/packages/driver-node/src/index.ts b/packages/driver-node/src/index.ts
index 0bb8f3bb..8894b6e7 100644
--- a/packages/driver-node/src/index.ts
+++ b/packages/driver-node/src/index.ts
@@ -1,4 +1,4 @@
-export { MemoryArtifactStore } from "./artifacts.js";
+export { MemoryResourceStore } from "./resources.js";
export { NodeDriver } from "./driver.js";
export {
ProducerRegistry,
diff --git a/packages/driver-node/src/resources.ts b/packages/driver-node/src/resources.ts
new file mode 100644
index 00000000..6a4b5b47
--- /dev/null
+++ b/packages/driver-node/src/resources.ts
@@ -0,0 +1,32 @@
+import { randomUUID } from "node:crypto";
+
+import type { BlobRef, ResourceId } from "@hypit/protocol";
+import type { ResourceStore } from "@hypit/runtime";
+
+export class MemoryResourceStore implements ResourceStore {
+ readonly #values = new Map<ResourceId, Uint8Array>();
+
+ async put(bytes: Uint8Array, mediaType: string): Promise<BlobRef> {
+ const copy = Uint8Array.from(bytes);
+ const resource = `res_${randomUUID()}` as ResourceId;
+ this.#values.set(resource, copy);
+ return { kind: "blob", resource, size: copy.byteLength, mediaType };
+ }
+
+ async write(resource: BlobRef, bytes: Uint8Array): Promise<void> {
+ const copy = Uint8Array.from(bytes);
+ if (copy.byteLength !== resource.size) {
+ throw new Error(`Resource ${resource.resource} has size ${copy.byteLength}, expected ${resource.size}`);
+ }
+ if (!this.#values.has(resource.resource)) this.#values.set(resource.resource, copy);
+ }
+
+ async get(resource: ResourceId): Promise<Uint8Array | undefined> {
+ const value = this.#values.get(resource);
+ return value === undefined ? undefined : Uint8Array.from(value);
+ }
+
+ async has(resource: ResourceId): Promise<boolean> {
+ return this.#values.has(resource);
+ }
+}
diff --git a/packages/driver-node/test/driver.test.ts b/packages/driver-node/test/driver.test.ts
index 0d3ae9f7..d804accf 100644
--- a/packages/driver-node/test/driver.test.ts
+++ b/packages/driver-node/test/driver.test.ts
@@ -4,7 +4,7 @@ import test from "node:test";
import { reduce } from "@hypit/core";
import {
ProducerRegistry,
- MemoryArtifactStore,
+ MemoryResourceStore,
NodeDriver,
EndpointRegistry,
} from "@hypit/driver-node";
@@ -206,17 +206,17 @@ test("an alternate Candidate is explicitly selected before execution, never by E
assert.equal(accepted.state.needs.length, 0);
});
-test("MemoryArtifactStore is content addressed and returns defensive copies", async () => {
- const store = new MemoryArtifactStore();
+test("MemoryResourceStore keeps independent admissions and returns defensive copies", async () => {
+ const store = new MemoryResourceStore();
const source = new Uint8Array([1, 2, 3]);
const first = await store.put(source, "application/octet-stream");
source[0] = 9;
const second = await store.put(new Uint8Array([1, 2, 3]), "application/octet-stream");
- assert.equal(first.digest, second.digest);
- const loaded = await store.get(first.digest);
+ assert.notEqual(first.resource, second.resource);
+ const loaded = await store.get(first.resource);
assert.deepEqual(loaded, new Uint8Array([1, 2, 3]));
if (loaded !== undefined) loaded[0] = 8;
- assert.deepEqual(await store.get(first.digest), new Uint8Array([1, 2, 3]));
+ assert.deepEqual(await store.get(first.resource), new Uint8Array([1, 2, 3]));
});
test("Core still owns scheduling when Driver has every implementation", async () => {
diff --git a/packages/elaborator/README.md b/packages/elaborator/README.md
index f5b7b765..951f2e35 100644
--- a/packages/elaborator/README.md
+++ b/packages/elaborator/README.md
@@ -27,7 +27,7 @@ duplicate aliases, decodes dependencies first, hygienically qualifies private Re
identities and binds only declared public exports into importer namespaces. Host filesystem paths
are excluded from Source Closure identity; source contents, Frontend digests and written import
edges remain covered. Every source asset actually requested during decode is also covered by its
-author-written locator and exact content-addressed `BlobRef`; raw bytes remain a Host transfer
+author-written locator and exact Resource `BlobRef`; raw bytes remain a Host transfer
concern and never enter the parser-independent AuthorModule or Core BuildState.
The same hygienic pass emits an ephemeral `hypit.author-provenance@1` sidecar. A Frontend may retain
diff --git a/packages/elaborator/src/source.ts b/packages/elaborator/src/source.ts
index 4b4dcb55..a402a9d5 100644
--- a/packages/elaborator/src/source.ts
+++ b/packages/elaborator/src/source.ts
@@ -1,5 +1,5 @@
import { link } from "@hypit/core";
-import { canonicalStringify, isDigest } from "@hypit/protocol";
+import { canonicalStringify, isResourceId } from "@hypit/protocol";
import type {
CompiledGraph,
GraphValueRef,
@@ -498,7 +498,7 @@ export async function compileSourceClosure(
const resolved = await request.resolveAsset(rawSource, assetRequest);
const artifact = resolved.artifact;
assert(artifact.kind === "blob", "INVALID_SOURCE_ASSET", `${assetRequest.from} did not resolve to a BlobRef`);
- assert(isDigest(artifact.digest), "INVALID_SOURCE_ASSET_DIGEST", `${assetRequest.from} has an invalid digest`);
+ assert(isResourceId(artifact.resource), "INVALID_SOURCE_ASSET_DIGEST", `${assetRequest.from} has an invalid digest`);
assert(Number.isSafeInteger(artifact.size) && artifact.size >= 0, "INVALID_SOURCE_ASSET_SIZE", `${assetRequest.from} has an invalid size`);
assert(
artifact.mediaType === assetRequest.mediaType,
diff --git a/packages/endpoint-kit/src/index.ts b/packages/endpoint-kit/src/index.ts
index 25547505..10a6a4b0 100644
--- a/packages/endpoint-kit/src/index.ts
+++ b/packages/endpoint-kit/src/index.ts
@@ -8,7 +8,7 @@ import type {
TypeRef,
} from "@hypit/protocol";
import type {
- ArtifactStore,
+ ResourceStore,
CredentialRef,
CredentialValue,
OperationFailure,
@@ -25,7 +25,7 @@ export type EndpointFulfillment = {
export type EndpointInvocationContext = {
readonly command: FulfillNeedCommand;
readonly need: Need;
- readonly artifacts: ArtifactStore;
+ readonly resources: ResourceStore;
/** Only slots explicitly declared by this configured Endpoint instance are present. */
readonly credentials: Readonly<Record<string, CredentialValue>>;
};
diff --git a/packages/film/test/film.test.ts b/packages/film/test/film.test.ts
index e64be4a3..e8cef9a7 100644
--- a/packages/film/test/film.test.ts
+++ b/packages/film/test/film.test.ts
@@ -9,7 +9,7 @@ import type { FontArtifactRef } from "@hypit/media";
import { sealCanvasSpace, spatialTypes } from "@hypit/spatial";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import {
@@ -61,7 +61,7 @@ const filmProgram = sealFilmProgram({
});
const titleFont: FontArtifactRef = {
sources: [{ artifact: {
- kind: "blob", digest: fixtureDigest("film-test-title-font"), size: 1, mediaType: "font/woff2",
+ kind: "blob", resource: fixtureResource("film-test-title-font"), size: 1, mediaType: "font/woff2",
} }],
weight: 800,
style: "normal",
diff --git a/packages/film/test/surface.test.ts b/packages/film/test/surface.test.ts
index 0e6dbb77..96969399 100644
--- a/packages/film/test/surface.test.ts
+++ b/packages/film/test/surface.test.ts
@@ -6,7 +6,7 @@ import { compositionDependency, compositionTypes, sealAudioTrack, sealVisualTrac
import type { Track } from "@hypit/composition";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import { createResolvedClosure, sealBuildRequest, start } from "@hypit/core";
@@ -39,7 +39,7 @@ import {
import { createRecordAdmitter, TypeValidatorRegistry } from "@hypit/validation";
const fixtureModule = { name: "example.film-fixture", version: "1" } as const;
-const fixtureSurfaceDigest = fixtureDigest("example.film-fixture/inputs-surface@1");
+const fixtureSurfaceDigest = fixtureResource("example.film-fixture/inputs-surface@1");
const fixtureSurface = {
name: "inputs", tag: "Inputs", mode: "structured",
outputs: [semanticTrackTypes.track, compositionTypes.visualTrack, compositionTypes.audioTrack],
diff --git a/packages/fonts-open/README.md b/packages/fonts-open/README.md
index 4c672b50..1e1a0080 100644
--- a/packages/fonts-open/README.md
+++ b/packages/fonts-open/README.md
@@ -1,7 +1,7 @@
# `@hypit/fonts-open`
Workspace package exposing 109 redistributable open font families as exact,
-content-addressed `FontArtifactRef` values. The installed packages carry their font bytes and license
+Resource-backed `FontArtifactRef` values. The installed packages carry their font bytes and license
files. Author compilation and rendering never download fonts or inspect system font directories.
A developer who pulls this repository gets the catalog with the ordinary `pnpm install`; importing
@@ -69,7 +69,7 @@ and license metadata; `openFontFamiliesByCategory` is suitable for a frontend pi
Latin variable faces intentionally load the compact Latin subset. CJK, world-script and Emoji
families preserve every Unicode-range shard from their installed CSS as one logical face. Only
-faces referenced by the Author Graph enter a Build transfer bundle and ArtifactStore.
+faces referenced by the Author Graph enter a Build transfer bundle and ResourceStore.
Every catalog entry is either SIL OFL 1.1 or Apache 2.0. Tests compare the declared license against
the installed package's own metadata. Private local fonts are not bundled: public redistribution
diff --git a/packages/fonts-open/src/manifest.ts b/packages/fonts-open/src/manifest.ts
index 9200303f..1ece8dc2 100644
--- a/packages/fonts-open/src/manifest.ts
+++ b/packages/fonts-open/src/manifest.ts
@@ -11,7 +11,7 @@ export const fontsOpenMarkupSurfaces = [{
mode: "structured",
outputs: [mediaTypes.fontArtifact],
vocabulary: {
- summary: "Materializes one exact catalog face as a content-addressed FontArtifact.",
+ summary: "Materializes one exact catalog face as a FontArtifact Resource.",
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the FontArtifact Record this element publishes." },
diff --git a/packages/fonts-open/src/surface.ts b/packages/fonts-open/src/surface.ts
index 7f58b482..491a1e73 100644
--- a/packages/fonts-open/src/surface.ts
+++ b/packages/fonts-open/src/surface.ts
@@ -141,13 +141,13 @@ async function materializeFace(
}));
const byArtifact = new Map<string, FontArtifactRef["sources"][number]>();
for (const source of resolvedSources) {
- const existing = byArtifact.get(source.artifact.digest);
+ const existing = byArtifact.get(source.artifact.resource);
if (existing === undefined) {
- byArtifact.set(source.artifact.digest, source);
+ byArtifact.set(source.artifact.resource, source);
continue;
}
if (existing.unicodeRange === undefined || source.unicodeRange === undefined) continue;
- byArtifact.set(source.artifact.digest, {
+ byArtifact.set(source.artifact.resource, {
artifact: existing.artifact,
unicodeRange: `${existing.unicodeRange},${source.unicodeRange}`,
});
diff --git a/packages/fonts-open/test/fonts-open.test.ts b/packages/fonts-open/test/fonts-open.test.ts
index 593d71ad..5d906e18 100644
--- a/packages/fonts-open/test/fonts-open.test.ts
+++ b/packages/fonts-open/test/fonts-open.test.ts
@@ -1,5 +1,4 @@
import assert from "node:assert/strict";
-import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import test from "node:test";
@@ -33,7 +32,7 @@ async function decode(
return {
artifact: {
kind: "blob",
- digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+ resource: `res_font-${requests.length}`,
size: bytes.byteLength,
mediaType: request.mediaType,
},
@@ -84,10 +83,7 @@ test("every declared family, static weight and style can materialize exact bytes
for (const style of family.styles) {
const { font, requests } = await decodeFace(name, String(weight), style);
assert.ok(font.sources.length > 0, `${name} ${weight} ${style}`);
- const uniqueBytes = new Set(requests.map(
- (request) => createHash("sha256").update(request.bytes).digest("hex"),
- ));
- assert.equal(uniqueBytes.size, font.sources.length, `${name} ${weight} ${style}`);
+ assert.equal(requests.length, font.sources.length, `${name} ${weight} ${style}`);
assert.equal(new Set(requests.map((request) => request.from)).size, requests.length, name);
}
}
diff --git a/packages/gemini/src/request.ts b/packages/gemini/src/request.ts
index ac8870b9..6ed16dba 100644
--- a/packages/gemini/src/request.ts
+++ b/packages/gemini/src/request.ts
@@ -27,7 +27,7 @@ export function verifyGeminiRequest(value: unknown): asserts value is GeminiRequ
for (const [index, raw] of request.media.entries()) {
const item = object(raw, `Gemini request media[${index}]`);
const artifact = object(item.artifact, `Gemini request media[${index}].artifact`);
- assert(artifact.kind === "blob" && typeof artifact.digest === "string"
+ assert(artifact.kind === "blob" && typeof artifact.resource === "string"
&& typeof artifact.size === "number" && Number.isSafeInteger(artifact.size)
&& typeof artifact.mediaType === "string",
`Gemini request media[${index}].artifact must be a BlobRef`);
diff --git a/packages/gemini/test/surface.test.ts b/packages/gemini/test/surface.test.ts
index 6e8d61fc..76ba5dc3 100644
--- a/packages/gemini/test/surface.test.ts
+++ b/packages/gemini/test/surface.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { decodeGeminiGenerateSurface, geminiCapabilities } from "@hypit/gemini";
import { artifactTypes } from "@hypit/artifact";
@@ -25,7 +25,7 @@ test("Gemini Surface builds one provider-neutral need with ordered media edges",
resolveReference: (path) => path === "video" ? {
path, ref: { kind: "record", id: "video" }, type: artifactTypes.blob,
record: { id: "video", type: artifactTypes.blob, value: {
- kind: "blob", digest: fixtureDigest("gemini-video"), size: 10, mediaType: "video/mp4",
+ kind: "blob", resource: fixtureResource("gemini-video"), size: 10, mediaType: "video/mp4",
} },
} : {
path, ref: { kind: "record", id: path }, type: textTypes.text,
diff --git a/packages/generation/README.md b/packages/generation/README.md
index be0f2242..41d70732 100644
--- a/packages/generation/README.md
+++ b/packages/generation/README.md
@@ -4,7 +4,7 @@ Provider-neutral generated-media contracts shared by exact image, video and audi
The package owns `GenerationRequest`, `GeneratedImageSet` and `GeneratedVideoSet` identities,
schemas, validators and graph facets. Generated sets are atomic Products: a Provider persists the
-returned bytes in an ArtifactStore and returns typed Blob references rather than transient URLs.
+returned bytes in an ResourceStore and returns typed Blob references rather than transient URLs.
This package does not choose a model, Provider, credential, queue or retry policy. Model packages
declare exact request Capabilities; Endpoint packages such as `@hypit/provider-kie` implement those
diff --git a/packages/generation/src/identity.ts b/packages/generation/src/identity.ts
index 420c41aa..1b54dbc4 100644
--- a/packages/generation/src/identity.ts
+++ b/packages/generation/src/identity.ts
@@ -1,6 +1,6 @@
import {
canonicalize,
- isDigest,
+ isResourceId,
} from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
@@ -28,7 +28,7 @@ export function assertGenerationBlobRef(
): asserts value is BlobRef {
const object = plainObject(value, "Generation artifact");
assert(object.kind === "blob", "Generation artifact must be a BlobRef");
- assert(typeof object.digest === "string" && isDigest(object.digest), "Generation artifact digest is invalid");
+ assert(typeof object.resource === "string" && isResourceId(object.resource), "Generation artifact resource is invalid");
assert(Number.isSafeInteger(object.size) && (object.size as number) >= 0, "Generation artifact size is invalid");
assert(typeof object.mediaType === "string" && object.mediaType.length > 0, "Generation artifact mediaType is invalid");
if (mediaPrefix !== undefined) {
diff --git a/packages/generation/src/index.ts b/packages/generation/src/index.ts
index 05ee0b13..1c45dcc8 100644
--- a/packages/generation/src/index.ts
+++ b/packages/generation/src/index.ts
@@ -70,7 +70,7 @@ export {
generatedAudioSetSchema,
generatedVideoSetSchema,
generationBlobRefSchema,
- generationDigestSchema,
+ generationResourceSchema,
generationObjectSchema,
generationPromptSchema,
} from "./schema.js";
diff --git a/packages/generation/src/schema.ts b/packages/generation/src/schema.ts
index 854fb95d..5f12765a 100644
--- a/packages/generation/src/schema.ts
+++ b/packages/generation/src/schema.ts
@@ -1,6 +1,6 @@
import type { ObjectFieldSchema, ValueSchema } from "@hypit/protocol";
-export const generationDigestSchema = {
+export const generationResourceSchema = {
kind: "string",
minLength: 71,
maxLength: 71,
@@ -16,7 +16,7 @@ export const generationBlobRefSchema = {
kind: "object",
fields: {
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: generationDigestSchema },
+ resource: { schema: generationResourceSchema },
size: { schema: { kind: "number", integer: true, minimum: 0 } },
mediaType: { schema: { kind: "string", minLength: 1, maxLength: 255 } },
},
diff --git a/packages/generation/test/identity.test.ts b/packages/generation/test/identity.test.ts
index da10deeb..396db062 100644
--- a/packages/generation/test/identity.test.ts
+++ b/packages/generation/test/identity.test.ts
@@ -2,7 +2,7 @@ import assert from "node:assert/strict";
import test from "node:test";
import { registerTypeValidatorFacets } from "@hypit/component-kit";
-import { MemoryArtifactStore } from "@hypit/driver-node";
+import { MemoryResourceStore } from "@hypit/driver-node";
import {
generationComponent,
generationProducers,
@@ -16,7 +16,7 @@ import {
import { TypeValidatorRegistry } from "@hypit/validation";
test("generated media validators bind artifacts and result contents", async () => {
- const store = new MemoryArtifactStore();
+ const store = new MemoryResourceStore();
const image = await store.put(new Uint8Array([4, 5, 6]), "image/png");
const result = sealGeneratedImageSet({
images: [image],
@@ -28,8 +28,8 @@ test("generated media validators bind artifacts and result contents", async () =
assert.ok(validators.resolve(generationTypes.imageSet));
});
-test("generated audio is an ordinary content-addressed media result", async () => {
- const store = new MemoryArtifactStore();
+test("generated audio is an ordinary Resource-backed media result", async () => {
+ const store = new MemoryResourceStore();
const audio = await store.put(new Uint8Array([7, 8, 9]), "audio/wav");
const set = sealGeneratedAudioSet({ audios: [audio] });
verifyGeneratedAudioSet(set);
@@ -45,7 +45,7 @@ test("generated audio is an ordinary content-addressed media result", async () =
});
test("the primary-video projection returns the ordered Product member as a Blob value", async () => {
- const store = new MemoryArtifactStore();
+ const store = new MemoryResourceStore();
const first = await store.put(new Uint8Array([1, 2, 3]), "video/mp4");
const second = await store.put(new Uint8Array([4, 5, 6]), "video/mp4");
const set = sealGeneratedVideoSet({
diff --git a/packages/generation/test/ports.test.ts b/packages/generation/test/ports.test.ts
index b51f155f..10aa06e2 100644
--- a/packages/generation/test/ports.test.ts
+++ b/packages/generation/test/ports.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { MemoryArtifactStore } from "@hypit/driver-node";
+import { MemoryResourceStore } from "@hypit/driver-node";
import {
assertMappingCoversPorts,
bindGenerationMedia,
@@ -79,7 +79,7 @@ const mapping: GenerationWireMapping = {
};
async function artifacts() {
- const store = new MemoryArtifactStore();
+ const store = new MemoryResourceStore();
return {
image: await store.put(new Uint8Array([1]), "image/png"),
video: await store.put(new Uint8Array([2]), "video/mp4"),
@@ -87,7 +87,7 @@ async function artifacts() {
};
}
-const resolve = async (artifact: { readonly digest: string }) => `https://cdn.test/${artifact.digest}`;
+const resolve = async (artifact: { readonly resource: string }) => `https://cdn.test/${artifact.resource}`;
test("a port table derives the request Schema and rejects undeclared ports", () => {
const schema = requestSchemaFromPorts(table);
@@ -163,11 +163,11 @@ test("one mapping compiles every port shape and routes by port presence", async
assert.deepEqual(wire.input, {
duration: "8",
prompt: "hello",
- reference_audio_urls: [`https://cdn.test/${audio.digest}`],
- reference_image_urls: [`https://cdn.test/${image.digest}`],
+ reference_audio_urls: [`https://cdn.test/${audio.resource}`],
+ reference_image_urls: [`https://cdn.test/${image.resource}`],
resolution: "720p",
return_last_frame: false,
- video_list: [{ ends: 4, start: 1, url: `https://cdn.test/${video.digest}` }],
+ video_list: [{ ends: 4, start: 1, url: `https://cdn.test/${video.resource}` }],
voice_ids: ["alpha", "beta"],
});
diff --git a/packages/gpt-image/test/broll-graph.test.ts b/packages/gpt-image/test/broll-graph.test.ts
index 887eafd2..faa08280 100644
--- a/packages/gpt-image/test/broll-graph.test.ts
+++ b/packages/gpt-image/test/broll-graph.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { artifactManifest, artifactTypes } from "@hypit/artifact";
import {
@@ -30,7 +30,7 @@ import { exactModelMediaInputNames } from "@hypit/model-kit";
import { mediaManifest } from "@hypit/media";
import { narrativeManifest } from "@hypit/narrative";
import { programSpaceManifest } from "@hypit/program-space";
-import type { CanonicalValue, Digest, ModuleManifest, StoredValue, TypeRef } from "@hypit/protocol";
+import type { CanonicalValue, ResourceId, ModuleManifest, StoredValue, TypeRef } from "@hypit/protocol";
import { rasterManifest } from "@hypit/raster";
import { createProvidedCandidate } from "@hypit/run";
import {
@@ -46,7 +46,7 @@ import { textManifest } from "@hypit/text";
const image = (name: string) => ({
kind: "blob" as const,
- digest: fixtureDigest(`image:${name}`),
+ resource: fixtureResource(`image:${name}`),
size: 100,
mediaType: "image/png",
});
diff --git a/packages/hyperframes/README.md b/packages/hyperframes/README.md
index 4c6418a8..78fce60b 100644
--- a/packages/hyperframes/README.md
+++ b/packages/hyperframes/README.md
@@ -18,12 +18,12 @@ It deliberately ignores `AudioTrack`. HyperFrames produces a silent visual fact;
compiles and renders program audio separately, then an explicit mux Provider joins the two. Changing
audio can therefore never be implemented by secretly changing HyperFrames HTML or its renderer.
-Media remains content addressed in the compiled HTML as `hypit-artifact://` placeholders. The
-document separately carries each dependency's complete `BlobRef` (digest, byte count and MIME), so
+Media remains resource-referenced in compiled HTML as `hypit-resource://` placeholders. The
+document separately carries each dependency's complete `BlobRef` (Resource id, byte count and MIME), so
a Provider can verify and name staged bytes without guessing from the hash. A local or hosted
render Runtime calls `materializeHyperframesHtml()` with its own Artifact URL resolver before
handing the HTML to HyperFrames. That environment-specific materialization is not a new compiled
-Record and does not change the document digest.
+Record and does not change the compiled document.
The document exposes its render domain directly rather than asking an Endpoint to scrape HTML:
exact rational `frameRate`, integer `frameCount`, and canvas dimensions are explicit document
diff --git a/packages/hyperframes/src/document.ts b/packages/hyperframes/src/document.ts
index b1b6526e..4cd4060e 100644
--- a/packages/hyperframes/src/document.ts
+++ b/packages/hyperframes/src/document.ts
@@ -1,5 +1,3 @@
-import { createHash } from "node:crypto";
-
import { assertCompositableSurfaceRef } from "@hypit/media";
import type { CompositableSurfaceRef, FontArtifactRef } from "@hypit/media";
import { programSpaceFrameCount } from "@hypit/program-space";
@@ -17,12 +15,12 @@ import type {
VisualStyleDeclaration,
VisualTrack,
} from "@hypit/composition";
-import { canonicalStringify, isDigest } from "@hypit/protocol";
-import type { BlobRef, Digest } from "@hypit/protocol";
+import { canonicalStringify, isResourceId } from "@hypit/protocol";
+import type { BlobRef, ResourceId } from "@hypit/protocol";
import { VISUAL_IR_V1 } from "@hypit/visual-ir";
import type {
- ArtifactUrlResolver,
+ ResourceUrlResolver,
HyperframesDocument,
HyperframesFrameSpan,
} from "./types.js";
@@ -34,8 +32,8 @@ import {
} from "./text.js";
const NANOSECONDS = 1_000_000_000n;
-const ARTIFACT_URI = /hypit-artifact:\/\/sha256\/([0-9a-f]{64})/gu;
-const SURFACE_ARTIFACT = /data-hypit-surface-artifact="(sha256:[0-9a-f]{64})"/gu;
+const RESOURCE_URI = /hypit-resource:\/\/(res_[a-zA-Z0-9._:-]+)/gu;
+const SURFACE_RESOURCE = /data-hypit-surface-resource="(res_[a-zA-Z0-9._:-]+)"/gu;
function escapeHtml(value: string): string {
return value
@@ -178,9 +176,9 @@ function percentage(frame: number, totalFrames: number): string {
return `${whole}.${String(remainder).padStart(9, "0").replace(/0+$/u, "")}%`;
}
-export function hyperframesArtifactUri(digest: Digest): string {
- if (!isDigest(digest)) throw new Error("HyperFrames Artifact digest is invalid.");
- return `hypit-artifact://sha256/${digest.slice("sha256:".length)}`;
+export function hyperframesResourceUri(resource: ResourceId): string {
+ if (!isResourceId(resource)) throw new Error("HyperFrames Resource id is invalid.");
+ return `hypit-resource://${resource}`;
}
function css(style: readonly VisualStyleDeclaration[]): string {
@@ -200,34 +198,30 @@ function attributes(values: readonly VisualAttribute[] | undefined): string {
return (values ?? []).map(({ name, value }) => ` ${name}="${escapeHtml(value)}"`).join("");
}
-/**
- * Name a DOM node after what it is, in a fixed number of characters.
- *
- * HyperFrames reads the `<video>` element's id back out of the document and spends it as a
- * directory name for that video's extracted frames. On Windows those frames live under
- * `%TEMP%\hf-render-…`, which leaves around 150 characters before the path stops being one. An
- * identity that carried its parts verbatim did not fit: a Track spanning five takes names all
- * five, the Present and the layer each repeat the Track's name, and encoding the three of them
- * multiplied the result again. A single take was already within five characters of the limit.
- *
- * A digest is the same identity at a length that does not depend on how much was said. It is
- * still stable, so the document still renders the same bytes for the same composition and the
- * frame cache still hits. Nothing reads the parts back: `data-hypit-element-id` and
- * `data-hypit-track-id` carry them, spelled the way an author wrote them.
- */
-function stableDomId(parts: readonly string[]): string {
- return `hypit-${createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 24)}`;
+type StableDomId = (parts: readonly string[]) => string;
+
+/** Allocate short document-local names in first-use order; authored ids stay in data attributes. */
+function createStableDomId(): StableDomId {
+ const ids = new Map<string, string>();
+ return (parts) => {
+ const key = canonicalStringify(parts);
+ const existing = ids.get(key);
+ if (existing !== undefined) return existing;
+ const id = `hypit-${ids.size + 1}`;
+ ids.set(key, id);
+ return id;
+ };
}
-function exactFontFamily(font: FontArtifactRef): string {
- return stableDomId(["font", canonicalStringify(font)]);
+function exactFontFamily(font: FontArtifactRef, stableId: StableDomId): string {
+ return stableId(["font", canonicalStringify(font)]);
}
-function exactFontStyle(element: VisualElement): string[] {
+function exactFontStyle(element: VisualElement, stableId: StableDomId): string[] {
if (element.kind !== "text") return [];
const first = element.fonts[0]!;
return [
- `font-family:${element.fonts.map(exactFontFamily).join(",")}`,
+ `font-family:${element.fonts.map((font) => exactFontFamily(font, stableId)).join(",")}`,
`font-weight:${first.weight}`,
`font-style:${first.style}`,
"font-synthesis:none",
@@ -248,12 +242,13 @@ function renderElement(
readonly programDenominator: number;
readonly stackIndex: number;
readonly emittedFilterIds: Set<string>;
+ readonly stableId: StableDomId;
},
): string {
- const id = stableDomId([context.trackId, context.presentId, element.id]);
+ const id = context.stableId([context.trackId, context.presentId, element.id]);
const animationName = element.animation === undefined
? undefined
- : stableDomId(["animation", context.trackId, context.presentId, element.id]);
+ : context.stableId(["animation", context.trackId, context.presentId, element.id]);
const animationProperties = element.animation === undefined
? []
: [...new Set(element.animation.keyframes.flatMap((keyframe) => keyframe.style.map((declaration) => declaration.name)))].sort();
@@ -263,7 +258,7 @@ function renderElement(
const animationDuration = frameSeconds(animationDurationFrames, context.programNumerator, context.programDenominator);
const inlineStyle = [
css(element.style),
- ...exactFontStyle(element),
+ ...exactFontStyle(element, context.stableId),
...(animationName === undefined ? [] : [
`animation-name:${animationName}`,
`animation-duration:${animationDuration}s`,
@@ -288,7 +283,7 @@ function renderElement(
if (maskRoot === undefined || contentRoot === undefined || direct.length !== 2) {
throw new Error(`Local mask ${element.id} is missing its declared owned roots.`);
}
- const maskId = stableDomId([context.trackId, context.presentId, element.id, "mask"]);
+ const maskId = context.stableId([context.trackId, context.presentId, element.id, "mask"]);
const maskWidth = pixelDimension(element.style, "width");
const maskHeight = pixelDimension(element.style, "height");
const viewport = maskWidth === undefined || maskHeight === undefined
@@ -314,17 +309,17 @@ function renderElement(
? blockAlignment === "flex-start" ? "0" : blockAlignment === "flex-end" ? "100%" : "50%"
: String(blockAlignment === "flex-start" ? paddingTop : blockAlignment === "flex-end" ? maskHeight - paddingBottom : (paddingTop + maskHeight - paddingBottom) / 2);
const baseline = blockAlignment === "flex-start" ? "text-before-edge" : blockAlignment === "flex-end" ? "text-after-edge" : "central";
- const textStyle = [css(maskRoot.style), ...exactFontStyle(maskRoot), "fill:currentColor"].filter(Boolean).join(";");
+ const textStyle = [css(maskRoot.style), ...exactFontStyle(maskRoot, context.stableId), "fill:currentColor"].filter(Boolean).join(";");
return `<text${attributes(maskRoot.attributes)} x="${x}" y="${y}" text-anchor="${anchor}" dominant-baseline="${baseline}" style="${escapeHtml(textStyle)}">${escapeHtml(maskRoot.text)}</text>`;
}
if (maskRoot.kind === "text-flow" || maskRoot.kind === "path-text") {
return `<foreignObject x="0" y="0" width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="position:relative;width:100%;height:100%">${renderOwned(maskRoot)}</div></foreignObject>`;
}
if (maskRoot.kind === "image") {
- return `<image x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesArtifactUri(maskRoot.artifact.digest))}" style="${escapeHtml(css(maskRoot.style))}"/>`;
+ return `<image x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesResourceUri(maskRoot.artifact.resource))}" style="${escapeHtml(css(maskRoot.style))}"/>`;
}
if (maskRoot.kind === "surface" && maskRoot.surface.timing.kind === "still") {
- return `<image data-hypit-surface-artifact="${maskRoot.surface.artifact.digest}" x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesArtifactUri(maskRoot.surface.artifact.digest))}" style="${escapeHtml(css(maskRoot.style))}"/>`;
+ return `<image data-hypit-surface-resource="${maskRoot.surface.artifact.resource}" x="0" y="0" width="100%" height="100%" preserveAspectRatio="none" href="${escapeHtml(hyperframesResourceUri(maskRoot.surface.artifact.resource))}" style="${escapeHtml(css(maskRoot.style))}"/>`;
}
throw new Error(`Local mask ${element.id} requires a terminal owned text, image or still Surface mask source.`);
})();
@@ -343,8 +338,8 @@ function renderElement(
programNumerator: context.programNumerator,
programDenominator: context.programDenominator,
escape: escapeHtml,
- stableId: stableDomId,
- exactFontFamily,
+ stableId: context.stableId,
+ exactFontFamily: (font: FontArtifactRef) => exactFontFamily(font, context.stableId),
baseStyle: inlineStyle,
commonAttributes,
emittedFilterIds: context.emittedFilterIds,
@@ -360,7 +355,7 @@ function renderElement(
}
if ((element.kind === "video" || element.kind === "surface") && element.sampling !== undefined) {
const artifact = element.kind === "surface" ? element.surface.artifact : element.artifact;
- const source = escapeHtml(hyperframesArtifactUri(artifact.digest));
+ const source = escapeHtml(hyperframesResourceUri(artifact.resource));
let part = 0;
return element.sampling.segments.flatMap((segment) => samplingRuns(segment).map((run) => {
part += 1;
@@ -383,7 +378,7 @@ function renderElement(
"muted",
"playsinline",
...(element.kind === "surface" ? [
- `data-hypit-surface-artifact="${element.surface.artifact.digest}"`,
+ `data-hypit-surface-resource="${element.surface.artifact.resource}"`,
`data-hypit-alpha-mode="${element.surface.alphaMode}"`,
`data-hypit-color-space="${element.surface.colorSpace}"`,
`width="${element.surface.width}"`,
@@ -394,9 +389,9 @@ function renderElement(
})).join("");
}
if (element.kind === "surface") {
- const source = escapeHtml(hyperframesArtifactUri(element.surface.artifact.digest));
+ const source = escapeHtml(hyperframesResourceUri(element.surface.artifact.resource));
const surface = [
- `data-hypit-surface-artifact="${element.surface.artifact.digest}"`,
+ `data-hypit-surface-resource="${element.surface.artifact.resource}"`,
`data-start="${context.presentStart}"`,
`data-duration="${context.presentDuration}"`,
`data-track-index="${context.stackIndex}"`,
@@ -416,7 +411,7 @@ function renderElement(
element.kind === "video" && element.muted !== false ? "muted" : "",
element.kind === "video" ? "playsinline" : "",
].filter(Boolean).join(" ");
- const source = escapeHtml(hyperframesArtifactUri(element.artifact.digest));
+ const source = escapeHtml(hyperframesResourceUri(element.artifact.resource));
if (element.kind === "image") return `<img ${common} ${media} src="${source}"/>`;
return `<video ${common} ${media} src="${source}">${descendants}</video>`;
}
@@ -428,6 +423,7 @@ function renderVisualPresent(
numerator: number,
denominator: number,
emittedFilterIds: Set<string>,
+ stableId: StableDomId,
): string {
const start = frameSeconds(present.span.startFrame, numerator, denominator);
const duration = frameSeconds(present.span.endFrameExclusive - present.span.startFrame, numerator, denominator);
@@ -451,16 +447,17 @@ function renderVisualPresent(
programDenominator: denominator,
stackIndex,
emittedFilterIds,
+ stableId,
});
return `<div class="clip hypit-visual-present" data-hypit-track-id="${escapeHtml(track.id)}" data-hypit-present-id="${escapeHtml(present.id)}" data-hypit-stack-order="${present.stacking.order}" data-hypit-stack-tie="${escapeHtml(present.stacking.tieBreak)}" data-track-index="${stackIndex}" data-start="${start}" data-duration="${duration}" style="position:absolute;inset:0;z-index:${stackIndex};overflow:hidden;pointer-events:none">${contents}</div>`;
}
-function renderAnimationRules(track: VisualTrack, present: VisualPresent): string[] {
+function renderAnimationRules(track: VisualTrack, present: VisualPresent, stableId: StableDomId): string[] {
const presentDurationFrames = present.span.endFrameExclusive - present.span.startFrame;
return present.elements.flatMap((element) => {
if (element.animation === undefined) return [];
const durationFrames = Math.max(presentDurationFrames, element.animation.keyframes.at(-1)?.atFrame ?? 0);
- const name = stableDomId(["animation", track.id, present.id, element.id]);
+ const name = stableId(["animation", track.id, present.id, element.id]);
const keyframes: VisualAnimation["keyframes"] = element.animation.keyframes.at(-1)?.atFrame === durationFrames
? element.animation.keyframes
: [...element.animation.keyframes, {
@@ -487,19 +484,19 @@ function orderedVisualPresents(tracks: readonly Track[]): Array<{ readonly track
}
function collectArtifacts(composition: Composition): BlobRef[] {
- const artifacts = new Map<Digest, BlobRef>();
- const add = (artifact: Pick<BlobRef, "digest" | "size" | "mediaType">): void => {
+ const artifacts = new Map<ResourceId, BlobRef>();
+ const add = (artifact: Pick<BlobRef, "resource" | "size" | "mediaType">): void => {
const next: BlobRef = {
kind: "blob",
- digest: artifact.digest,
+ resource: artifact.resource,
size: artifact.size,
mediaType: artifact.mediaType,
};
- const existing = artifacts.get(artifact.digest);
+ const existing = artifacts.get(artifact.resource);
if (existing !== undefined && (existing.size !== next.size || existing.mediaType !== next.mediaType)) {
- throw new Error(`HyperFrames Artifact ${artifact.digest} has conflicting metadata.`);
+ throw new Error(`HyperFrames Artifact ${artifact.resource} has conflicting metadata.`);
}
- artifacts.set(artifact.digest, next);
+ artifacts.set(artifact.resource, next);
};
for (const track of composition.tracks) {
if (track.kind === "audio") continue;
@@ -520,27 +517,27 @@ function collectArtifacts(composition: Composition): BlobRef[] {
}
}
}
- return [...artifacts.values()].sort((left, right) => left.digest.localeCompare(right.digest));
+ return [...artifacts.values()].sort((left, right) => left.resource.localeCompare(right.resource));
}
function collectSurfaces(composition: Composition): CompositableSurfaceRef[] {
- const surfaces = new Map<Digest, CompositableSurfaceRef>();
+ const surfaces = new Map<ResourceId, CompositableSurfaceRef>();
for (const track of composition.tracks) {
if (track.kind !== "visual") continue;
for (const present of track.presents) {
for (const element of present.elements) {
if (element.kind !== "surface") continue;
const surface = structuredClone(element.surface);
- const existing = surfaces.get(surface.artifact.digest);
+ const existing = surfaces.get(surface.artifact.resource);
if (existing !== undefined && canonicalStringify(existing) !== canonicalStringify(surface)) {
- throw new Error(`HyperFrames Surface ${surface.artifact.digest} has conflicting declarations.`);
+ throw new Error(`HyperFrames Surface ${surface.artifact.resource} has conflicting declarations.`);
}
- surfaces.set(surface.artifact.digest, surface);
+ surfaces.set(surface.artifact.resource, surface);
}
}
}
return [...surfaces.values()].sort((left, right) =>
- left.artifact.digest.localeCompare(right.artifact.digest));
+ left.artifact.resource.localeCompare(right.artifact.resource));
}
function collectFonts(composition: Composition): FontArtifactRef[] {
@@ -573,11 +570,11 @@ function fontFormat(mediaType: string): string {
return "truetype";
}
-function renderFontFaces(composition: Composition): string {
+function renderFontFaces(composition: Composition, stableId: StableDomId): string {
return collectFonts(composition).flatMap((font) => font.sources.map((source) => [
"@font-face{",
- `font-family:${exactFontFamily(font)};`,
- `src:url(\"${hyperframesArtifactUri(source.artifact.digest)}\") format(\"${fontFormat(source.artifact.mediaType)}\");`,
+ `font-family:${exactFontFamily(font, stableId)};`,
+ `src:url(\"${hyperframesResourceUri(source.artifact.resource)}\") format(\"${fontFormat(source.artifact.mediaType)}\");`,
`font-weight:${font.weight};`,
`font-style:${font.style};`,
"font-display:block;",
@@ -645,9 +642,10 @@ function emitHtml(composition: Composition, programSpace: ProgramSpace): string
// One document, one set of glyph filter definitions: every Present writes only what is not
// already there, and references resolve across the document regardless of where they landed.
const emittedFilterIds = new Set<string>();
- const visualHtml = visuals.map(({ track, present }, index) => renderVisualPresent(track, present, index, numerator, denominator, emittedFilterIds)).join("\n ");
- const animationCss = visuals.flatMap(({ track, present }) => renderAnimationRules(track, present)).join("\n ");
- const fontCss = renderFontFaces(composition);
+ const stableId = createStableDomId();
+ const visualHtml = visuals.map(({ track, present }, index) => renderVisualPresent(track, present, index, numerator, denominator, emittedFilterIds, stableId)).join("\n ");
+ const animationCss = visuals.flatMap(({ track, present }) => renderAnimationRules(track, present, stableId)).join("\n ");
+ const fontCss = renderFontFaces(composition, stableId);
const duration = frameSeconds(programSpaceFrameCount(programSpace), numerator, denominator);
const fps = fpsRational(numerator, denominator);
const frameCount = programSpaceFrameCount(programSpace);
@@ -687,10 +685,10 @@ function normalizedDocument(value: HyperframesDocument): HyperframesDocument {
canvas: { ...value.canvas },
artifacts: [...value.artifacts]
.map((artifact) => ({ ...artifact }))
- .sort((left, right) => left.digest.localeCompare(right.digest)),
+ .sort((left, right) => left.resource.localeCompare(right.resource)),
surfaces: [...value.surfaces]
.map((surface) => structuredClone(surface))
- .sort((left, right) => left.artifact.digest.localeCompare(right.artifact.digest)),
+ .sort((left, right) => left.artifact.resource.localeCompare(right.artifact.resource)),
html: value.html,
};
}
@@ -730,25 +728,25 @@ export function assertHyperframesDocument(document: HyperframesDocument): void {
}
if (!document.html.startsWith("<!doctype html>")) throw new Error("HyperframesDocument HTML is invalid.");
const declared = [...document.artifacts];
- if (declared.some((item) => item.kind !== "blob" || !isDigest(item.digest)
+ if (declared.some((item) => item.kind !== "blob" || !isResourceId(item.resource)
|| !Number.isSafeInteger(item.size) || item.size < 0 || item.mediaType.length === 0)
- || new Set(declared.map((item) => item.digest)).size !== declared.length) {
+ || new Set(declared.map((item) => item.resource)).size !== declared.length) {
throw new Error("HyperframesDocument Artifact set is invalid.");
}
- const referenced = [...document.html.matchAll(ARTIFACT_URI)].map((match) => `sha256:${match[1]}` as Digest);
+ const referenced = [...document.html.matchAll(RESOURCE_URI)].map((match) => match[1] as ResourceId);
const actual = [...new Set(referenced)].sort();
- if (JSON.stringify(actual) !== JSON.stringify(declared.map((item) => item.digest).sort())) {
+ if (JSON.stringify(actual) !== JSON.stringify(declared.map((item) => item.resource).sort())) {
throw new Error("HyperframesDocument Artifact placeholders do not match its declared dependencies.");
}
if (!Array.isArray(document.surfaces)) throw new Error("HyperframesDocument Surface set is invalid.");
const surfaceArtifacts = new Set<string>();
for (const [index, surface] of document.surfaces.entries()) {
assertCompositableSurfaceRef(surface, `HyperframesDocument.surfaces.${index}`);
- if (surfaceArtifacts.has(surface.artifact.digest)) {
+ if (surfaceArtifacts.has(surface.artifact.resource)) {
throw new Error("HyperframesDocument Surface set repeats an Artifact.");
}
- surfaceArtifacts.add(surface.artifact.digest);
- const artifact = declared.find((item) => item.digest === surface.artifact.digest);
+ surfaceArtifacts.add(surface.artifact.resource);
+ const artifact = declared.find((item) => item.resource === surface.artifact.resource);
if (artifact === undefined
|| artifact.size !== surface.artifact.size
|| artifact.mediaType !== surface.artifact.mediaType) {
@@ -756,7 +754,7 @@ export function assertHyperframesDocument(document: HyperframesDocument): void {
}
}
const referencedSurfaces = [...new Set(
- [...document.html.matchAll(SURFACE_ARTIFACT)].map((match) => match[1]!),
+ [...document.html.matchAll(SURFACE_RESOURCE)].map((match) => match[1]!),
)].sort();
if (JSON.stringify(referencedSurfaces) !== JSON.stringify([...surfaceArtifacts].sort())) {
throw new Error("HyperframesDocument Surface markers do not match its typed dependencies.");
@@ -793,14 +791,13 @@ export function assertHyperframesFrameSpan(
/** Runtime-only URL materialization. The returned HTML is intentionally not a new compiled Record. */
export function materializeHyperframesHtml(
document: HyperframesDocument,
- resolve: ArtifactUrlResolver,
+ resolve: ResourceUrlResolver,
): string {
assertHyperframesDocument(document);
- const artifacts = new Map(document.artifacts.map((artifact) => [artifact.digest, artifact]));
- return document.html.replace(ARTIFACT_URI, (_uri, hash: string) => {
- const digest = `sha256:${hash}` as Digest;
- const artifact = artifacts.get(digest);
- if (artifact === undefined) throw new Error(`HyperFrames Artifact ${digest} is undeclared.`);
+ const artifacts = new Map(document.artifacts.map((artifact) => [artifact.resource, artifact]));
+ return document.html.replace(RESOURCE_URI, (_uri, resource: ResourceId) => {
+ const artifact = artifacts.get(resource);
+ if (artifact === undefined) throw new Error(`HyperFrames Resource ${resource} is undeclared.`);
return escapeHtml(resolve(artifact));
});
}
diff --git a/packages/hyperframes/src/index.ts b/packages/hyperframes/src/index.ts
index 9145364a..7ef5beec 100644
--- a/packages/hyperframes/src/index.ts
+++ b/packages/hyperframes/src/index.ts
@@ -1,6 +1,6 @@
export { hyperframesDocumentFragment } from "./fragment.js";
export { hyperframesComponent } from "./component.js";
-export { assertHyperframesDocument, assertHyperframesFrameIndex, assertHyperframesFrameSpan, compileHyperframesDocument, hyperframesArtifactUri, hyperframesTime, materializeHyperframesHtml } from "./document.js";
+export { assertHyperframesDocument, assertHyperframesFrameIndex, assertHyperframesFrameSpan, compileHyperframesDocument, hyperframesResourceUri, hyperframesTime, materializeHyperframesHtml } from "./document.js";
export {
hyperframesDocumentSchema,
hyperframesManifest,
diff --git a/packages/hyperframes/src/manifest.ts b/packages/hyperframes/src/manifest.ts
index 88468e99..491970cc 100644
--- a/packages/hyperframes/src/manifest.ts
+++ b/packages/hyperframes/src/manifest.ts
@@ -12,7 +12,7 @@ export const hyperframesProducers = {
compile: { module: hyperframesModuleRef, name: "compile-composition" },
} satisfies Record<string, ProducerRef>;
-const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
+const resource = { kind: "string", minLength: 5, maxLength: 256 } as const;
const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
const nonNegativeInteger = { kind: "number", integer: true, minimum: 0 } as const;
export const hyperframesDocumentSchema: ValueSchema = {
@@ -38,7 +38,7 @@ export const hyperframesDocumentSchema: ValueSchema = {
kind: "object",
fields: {
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: digest },
+ resource: { schema: resource },
size: { schema: nonNegativeInteger },
mediaType: { schema: { kind: "string", minLength: 1 } },
},
diff --git a/packages/hyperframes/src/project.ts b/packages/hyperframes/src/project.ts
index 42f9feb2..9c7a1ead 100644
--- a/packages/hyperframes/src/project.ts
+++ b/packages/hyperframes/src/project.ts
@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
import { mkdir, open, writeFile } from "node:fs/promises";
import { join } from "node:path";
@@ -8,7 +7,7 @@ import type { BlobRef } from "@hypit/protocol";
import { assertHyperframesDocument, materializeHyperframesHtml } from "./document.js";
import type { HyperframesDocument } from "./types.js";
-/** Reads one content-addressed dependency. Whose store it comes from is the caller's business. */
+/** Reads one execution resource. Whose store it comes from is the caller's business. */
export type HyperframesArtifactReader = (
artifact: BlobRef,
) => Promise<Uint8Array | AsyncIterable<Uint8Array>>;
@@ -40,11 +39,8 @@ function extension(mediaType: string): string {
*
* The same layout serves a local render and a distributed one: the local
* Provider points the CLI at it, and the AWS Provider tars it into a site. If
- * the two laid it out differently, one Need would name two different projects
- * and the content-addressed site id would stop meaning anything.
- *
- * Dependencies are named by digest, so a directory built twice from one
- * document is byte-identical and an unchanged tree re-uploads as a no-op.
+ * the two laid it out differently, one Need would name two different projects.
+ * Resource names are local to this staged project and carry no content claim.
*/
export async function stageHyperframesProject(options: {
readonly document: HyperframesDocument;
@@ -60,22 +56,20 @@ export async function stageHyperframesProject(options: {
const artifactDirectory = join(directory, "artifacts");
await mkdir(artifactDirectory, { recursive: true });
const paths = new Map<string, string>();
- const surfaces = new Map(document.surfaces.map((surface) => [surface.artifact.digest, surface]));
+ const surfaces = new Map(document.surfaces.map((surface) => [surface.artifact.resource, surface]));
await Promise.all(document.artifacts.map(async (artifact) => {
- const name = `${artifact.digest.slice("sha256:".length)}${extension(artifact.mediaType)}`;
+ const name = `${artifact.resource}${extension(artifact.mediaType)}`;
const opened = await read(artifact);
const chunks = opened instanceof Uint8Array
? (async function* () { yield opened; })()
: opened;
- const hash = createHash("sha256");
- const surface = surfaces.get(artifact.digest);
+ const surface = surfaces.get(artifact.resource);
const retained: Uint8Array[] = [];
let size = 0;
const target = await open(join(artifactDirectory, name), "w");
try {
for await (const chunk of chunks) {
await target.write(chunk);
- hash.update(chunk);
size += chunk.byteLength;
if (surface !== undefined) retained.push(Uint8Array.from(chunk));
}
@@ -83,11 +77,7 @@ export async function stageHyperframesProject(options: {
await target.close();
}
if (size !== artifact.size) {
- throw new Error(`HyperFrames Artifact ${artifact.digest} size differs`);
- }
- const digest = `sha256:${hash.digest("hex")}`;
- if (digest !== artifact.digest) {
- throw new Error(`HyperFrames Artifact ${artifact.digest} bytes differ`);
+ throw new Error(`HyperFrames Artifact ${artifact.resource} size differs`);
}
const bytes = surface === undefined ? undefined : (() => {
const value = new Uint8Array(size);
@@ -101,11 +91,11 @@ export async function stageHyperframesProject(options: {
if (surface !== undefined) {
await options.validateSurface!(structuredClone(surface), bytes!.slice());
}
- paths.set(artifact.digest, `./artifacts/${name}`);
+ paths.set(artifact.resource, `./artifacts/${name}`);
}));
const html = materializeHyperframesHtml(document, (artifact) => {
- const path = paths.get(artifact.digest);
- if (path === undefined) throw new Error(`HyperFrames Artifact ${artifact.digest} was not staged`);
+ const path = paths.get(artifact.resource);
+ if (path === undefined) throw new Error(`HyperFrames Artifact ${artifact.resource} was not staged`);
return path;
});
await writeFile(join(directory, "index.html"), html, "utf8");
diff --git a/packages/hyperframes/src/types.ts b/packages/hyperframes/src/types.ts
index dea6fe56..0529eb39 100644
--- a/packages/hyperframes/src/types.ts
+++ b/packages/hyperframes/src/types.ts
@@ -1,5 +1,5 @@
-import type { BlobRef, Digest } from "@hypit/protocol";
+import type { BlobRef, ResourceId } from "@hypit/protocol";
import type { CompositableSurfaceRef } from "@hypit/media";
export type HyperframesFrameDomain = {
@@ -16,15 +16,15 @@ export type HyperframesCanvas = {
readonly height: number;
};
-/** Deterministic, portable input to a local or remote HyperFrames renderer. */
+/** Portable input to a local or remote HyperFrames renderer. */
export type HyperframesDocument = HyperframesFrameDomain & {
readonly visualIr: typeof VISUAL_IR_V1;
readonly canvas: HyperframesCanvas;
- /** Every content-addressed byte dependency referenced by the HTML template. */
+ /** Every byte resource referenced by the HTML template. */
readonly artifacts: readonly BlobRef[];
/** Typed Surface dependencies that a Runtime must verify before rendering. */
readonly surfaces: readonly CompositableSurfaceRef[];
- /** Media URLs remain hypit-artifact:// placeholders until a Runtime materializes them. */
+ /** Media URLs remain hypit-resource:// placeholders until a Runtime materializes them. */
readonly html: string;
};
@@ -34,5 +34,5 @@ export type HyperframesFrameSpan = {
readonly endFrameExclusive: number;
};
-export type ArtifactUrlResolver = (artifact: BlobRef) => string;
+export type ResourceUrlResolver = (artifact: BlobRef) => string;
import { VISUAL_IR_V1 } from "@hypit/visual-ir";
diff --git a/packages/hyperframes/test/document.test.ts b/packages/hyperframes/test/document.test.ts
index dce36e17..02b826c0 100644
--- a/packages/hyperframes/test/document.test.ts
+++ b/packages/hyperframes/test/document.test.ts
@@ -13,10 +13,10 @@ import type { Track } from "@hypit/composition";
import { VISUAL_IR_V1 } from "@hypit/visual-ir";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
const fixtureFont: FontArtifactRef = {
- sources: [{ artifact: { kind: "blob", digest: fixtureDigest("hyperframes:fixture-font"), size: 1_024, mediaType: "font/woff2" } }],
+ sources: [{ artifact: { kind: "blob", resource: fixtureResource("hyperframes:fixture-font"), size: 1_024, mediaType: "font/woff2" } }],
weight: 700,
style: "normal",
};
@@ -28,13 +28,13 @@ function fixture() {
});
const picture = {
kind: "blob" as const,
- digest: fixtureDigest("hyperframes:picture"),
+ resource: fixtureResource("hyperframes:picture"),
size: 10,
mediaType: "image/png",
};
const sound = {
kind: "blob" as const,
- digest: fixtureDigest("hyperframes:sound"),
+ resource: fixtureResource("hyperframes:sound"),
size: 20,
mediaType: "audio/wav",
};
@@ -100,12 +100,12 @@ test("HyperFrames flattens generic peer visual Track Presents without absorbing
const document = compileHyperframesDocument(composition, programSpace);
assert.doesNotThrow(() => assertHyperframesDocument(document));
assert.equal(document.visualIr, VISUAL_IR_V1);
- assert.deepEqual(new Set(document.artifacts.map((artifact) => artifact.digest)),
- new Set([picture.digest, fixtureFont.sources[0]!.artifact.digest]));
+ assert.deepEqual(new Set(document.artifacts.map((artifact) => artifact.resource)),
+ new Set([picture.resource, fixtureFont.sources[0]!.artifact.resource]));
assert.ok(document.html.indexOf('data-hypit-track-id="lower"') < document.html.indexOf('data-hypit-track-id="upper"'));
assert.equal((document.html.match(/class="clip hypit-visual-present"/gu) ?? []).length, 2);
assert.doesNotMatch(document.html, /<audio/u);
- assert.doesNotMatch(document.html, new RegExp(sound.digest, "u"));
+ assert.doesNotMatch(document.html, new RegExp(sound.resource, "u"));
assert.doesNotMatch(document.html, /isolation:isolate|hypit-visual-track/u);
assert.match(document.html, /Hello &lt;world&gt;/u);
assert.match(document.html, /display:inline-grid/u);
@@ -223,12 +223,12 @@ test("Text shrink preserves authored hug sizing and trims metrics inside the con
test("visual Artifact placeholders are materialized only by the Runtime boundary", () => {
const { composition, picture, sound, programSpace } = fixture();
const document = compileHyperframesDocument(composition, programSpace);
- assert.match(document.html, /hypit-artifact:\/\/sha256\//u);
+ assert.match(document.html, /hypit-resource:\/\/res_/u);
const resolved = materializeHyperframesHtml(document,
- (artifact) => `https://assets.example/${artifact.digest}?x=1&y=2`);
- assert.doesNotMatch(resolved, /hypit-artifact:\/\//u);
- assert.match(resolved, new RegExp(`https://assets\\.example/${picture.digest}\\?x=1&amp;y=2`, "u"));
- assert.doesNotMatch(resolved, new RegExp(sound.digest, "u"));
+ (artifact) => `https://assets.example/${artifact.resource}?x=1&y=2`);
+ assert.doesNotMatch(resolved, /hypit-resource:\/\//u);
+ assert.match(resolved, new RegExp(`https://assets\\.example/${picture.resource}\\?x=1&amp;y=2`, "u"));
+ assert.doesNotMatch(resolved, new RegExp(sound.resource, "u"));
assert.equal(document.html.includes("assets.example"), false, "materialization must not mutate the compiled document");
});
@@ -332,14 +332,14 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
const font: FontArtifactRef = {
sources: [{ artifact: {
kind: "blob",
- digest: fixtureDigest("hyperframes:font"),
+ resource: fixtureResource("hyperframes:font"),
size: 1_024,
mediaType: "font/woff2",
} }],
weight: 700,
style: "normal",
};
- const surfaceDigest = fixtureDigest("hyperframes:alpha-surface");
+ const surfaceDigest = fixtureResource("hyperframes:alpha-surface");
const track = sealVisualTrack({ programSpaceId: "test-space",
visualIr: "hypit.visual-ir@1",
id: "bound-render-dependencies",
@@ -364,7 +364,7 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
order: 2,
kind: "surface",
surface: {
- artifact: { kind: "blob", digest: surfaceDigest, size: 2_048, mediaType: "video/webm" },
+ artifact: { kind: "blob", resource: surfaceDigest, size: 2_048, mediaType: "video/webm" },
width: 1080,
height: 1920,
colorSpace: "srgb",
@@ -386,16 +386,16 @@ test("content-bound fonts and typed compositable Surfaces cross the same Artifac
tracks: [track],
}), space);
assert.doesNotThrow(() => assertHyperframesDocument(document));
- assert.deepEqual(document.artifacts.map((artifact) => artifact.digest), [font.sources[0]!.artifact.digest, surfaceDigest].sort());
+ assert.deepEqual(document.artifacts.map((artifact) => artifact.resource), [font.sources[0]!.artifact.resource, surfaceDigest].sort());
assert.match(document.html, /@font-face\{/u);
assert.match(document.html, /format\("woff2"\)/u);
assert.match(document.html, /font-synthesis:none/u);
assert.match(document.html, /data-hypit-alpha-mode="straight"/u);
assert.match(document.html, /data-hypit-color-space="srgb"/u);
const materialized = materializeHyperframesHtml(document,
- (artifact) => `https://assets.example/${artifact.digest}?token=1&part=2`);
- assert.doesNotMatch(materialized, /hypit-artifact:\/\//u);
- assert.match(materialized, new RegExp(font.sources[0]!.artifact.digest, "u"));
+ (artifact) => `https://assets.example/${artifact.resource}?token=1&part=2`);
+ assert.doesNotMatch(materialized, /hypit-resource:\/\//u);
+ assert.match(materialized, new RegExp(font.sources[0]!.artifact.resource, "u"));
assert.match(materialized, new RegExp(surfaceDigest, "u"));
});
@@ -406,7 +406,7 @@ test("exact timed sampling lowers loop boundaries and held frames without zero-r
});
const artifact = {
kind: "blob" as const,
- digest: fixtureDigest("hyperframes:sampled-video"),
+ resource: fixtureResource("hyperframes:sampled-video"),
size: 1_000,
mediaType: "video/mp4",
};
@@ -482,7 +482,7 @@ test("a Track naming five takes still lowers to DOM identities a Windows path ca
kind: "video",
artifact: {
kind: "blob" as const,
- digest: fixtureDigest("hyperframes:long-identity-video"),
+ resource: fixtureResource("hyperframes:long-identity-video"),
size: 1_000,
mediaType: "video/mp4",
},
diff --git a/packages/image-compose/src/manifest.ts b/packages/image-compose/src/manifest.ts
index 501f3351..864482f2 100644
--- a/packages/image-compose/src/manifest.ts
+++ b/packages/image-compose/src/manifest.ts
@@ -20,7 +20,7 @@ const number = { kind: "number" } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
const blob = object({
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
size: { schema: { kind: "number", integer: true, minimum: 0 } },
mediaType: { schema: string },
});
diff --git a/packages/image-compose/src/program.ts b/packages/image-compose/src/program.ts
index 498bd3b5..8923e702 100644
--- a/packages/image-compose/src/program.ts
+++ b/packages/image-compose/src/program.ts
@@ -1,5 +1,5 @@
import { assertSpatialFrame } from "@hypit/spatial";
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import type {
ImageComposeLayer,
@@ -39,7 +39,7 @@ export function sealImageComposeLayerSpec(value: ImageComposeLayerSpec): ImageCo
}
function assertLayer(value: ImageComposeLayer, label: string): void {
- assert(value.source.kind === "blob" && isDigest(value.source.digest)
+ assert(value.source.kind === "blob" && isResourceId(value.source.resource)
&& Number.isSafeInteger(value.source.size) && value.source.size >= 0
&& value.source.mediaType.startsWith("image/"), `${label}.source must be an image BlobArtifact.`);
assertSpatialFrame(value.frame);
diff --git a/packages/image-compose/test/image-compose.test.ts b/packages/image-compose/test/image-compose.test.ts
index c0f9425b..b8dafd74 100644
--- a/packages/image-compose/test/image-compose.test.ts
+++ b/packages/image-compose/test/image-compose.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { artifactTypes } from "@hypit/artifact";
import {
@@ -25,7 +25,7 @@ const options = sealImageComposeOptions({ background: "#11223344" });
const spec = sealImageComposeLayerSpec({
fit: "cover", interpolation: "lanczos", opacity: 0.75,
});
-const source = { kind: "blob" as const, digest: fixtureDigest("hero-image"), size: 123, mediaType: "image/png" };
+const source = { kind: "blob" as const, resource: fixtureResource("hero-image"), size: 123, mediaType: "image/png" };
function record(id: string, type: TypeRef, value: StoredValue): TypedRecord {
return { id, type, value };
diff --git a/packages/image-transform/test/image-transform.test.ts b/packages/image-transform/test/image-transform.test.ts
index 33fc8c49..32e6d9e6 100644
--- a/packages/image-transform/test/image-transform.test.ts
+++ b/packages/image-transform/test/image-transform.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
decodeImageTransformProgramSurface,
@@ -71,7 +71,7 @@ test("the graph contract is exactly source plus Program to one image Need", asyn
const producer = imageTransformComponent.producers[0]!;
const source = {
kind: "blob" as const,
- digest: fixtureDigest("image-source"),
+ resource: fixtureResource("image-source"),
size: 123,
mediaType: "image/png",
};
diff --git a/packages/media-execution/src/execute.ts b/packages/media-execution/src/execute.ts
index 674044ba..63a8e614 100644
--- a/packages/media-execution/src/execute.ts
+++ b/packages/media-execution/src/execute.ts
@@ -1,7 +1,7 @@
import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
+import { randomUUID } from "node:crypto";
import { createReadStream } from "node:fs";
-import { mkdtemp, open, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, open, readFile, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { deflateSync } from "node:zlib";
@@ -46,7 +46,7 @@ import type { AnimatedWebp } from "./webp.js";
* Where the bytes live and which binaries transform them.
*
* These byte operations are the whole of Hypit's media execution, and they
- * are written once. A local Provider supplies the Build's own ArtifactStore and
+ * are written once. A local Provider supplies the Build's own ResourceStore and
* the ffmpeg on its PATH; a Lambda Provider supplies an S3-backed gateway and
* the ffmpeg carried by its deployment. Nothing below knows which it is, so the two
* deployments cannot drift into computing different media from one Need.
@@ -169,8 +169,8 @@ async function version(executable: string, timeoutMs: number, sharedLibraryPath?
async function sourceBytes(env: MediaExecutionEnvironment, source: BlobRef): Promise<Uint8Array> {
const bytes = await env.artifacts.get(source);
- assert(bytes !== undefined, `Media source ${source.digest} is unavailable`);
- assert(bytes.byteLength === source.size, `Media source ${source.digest} size differs`);
+ assert(bytes !== undefined, `Media source ${source.resource} is unavailable`);
+ assert(bytes.byteLength === source.size, `Media source ${source.resource} size differs`);
return bytes;
}
@@ -180,7 +180,7 @@ async function stageArtifact(
path: string,
): Promise<void> {
const chunks = await env.artifacts.open(source);
- assert(chunks !== undefined, `Media source ${source.digest} is unavailable`);
+ assert(chunks !== undefined, `Media source ${source.resource} is unavailable`);
const file = await open(path, "w");
let size = 0;
try {
@@ -191,7 +191,7 @@ async function stageArtifact(
} finally {
await file.close();
}
- assert(size === source.size, `Media source ${source.digest} size differs`);
+ assert(size === source.size, `Media source ${source.resource} size differs`);
}
function timestampFraction(value: MediaTimestamp): { numerator: bigint; denominator: bigint } {
@@ -428,15 +428,10 @@ async function outputInspection(args: {
readonly maxProbeOutputBytes: number;
readonly sharedLibraryPath?: string;
}): Promise<MediaInspection> {
- const hash = createHash("sha256");
- let size = 0;
- for await (const chunk of createReadStream(args.path)) {
- hash.update(chunk);
- size += chunk.byteLength;
- }
+ const size = (await stat(args.path)).size;
const source: BlobRef = {
kind: "blob",
- digest: `sha256:${hash.digest("hex")}` as BlobRef["digest"],
+ resource: `res_${randomUUID()}`,
size,
mediaType: args.mediaType,
};
@@ -1231,10 +1226,10 @@ export async function executeRenderTimelineAudio(
try {
const artifacts = new Map<string, { source: BlobRef; path: string; inputIndex: number; sampleFrames: number }>();
for (const clip of plan.clips) {
- const existing = artifacts.get(clip.artifact.digest);
+ const existing = artifacts.get(clip.artifact.resource);
if (existing !== undefined) {
assert(existing.sampleFrames === clip.sourceSampleFrames,
- `Audio input ${clip.artifact.digest} has conflicting sample counts in one plan`);
+ `Audio input ${clip.artifact.resource} has conflicting sample counts in one plan`);
continue;
}
const inputIndex = artifacts.size;
@@ -1249,8 +1244,8 @@ export async function executeRenderTimelineAudio(
...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
assert(audio.decodedSampleFrames === clip.sourceSampleFrames,
- `Audio input ${clip.artifact.digest} sample count differs from its plan`);
- artifacts.set(clip.artifact.digest, {
+ `Audio input ${clip.artifact.resource} sample count differs from its plan`);
+ artifacts.set(clip.artifact.resource, {
source: clip.artifact,
path,
inputIndex,
@@ -1268,7 +1263,7 @@ export async function executeRenderTimelineAudio(
);
} else {
const chains = plan.clips.map((clip, index) => {
- const inputIndex = artifacts.get(clip.artifact.digest)!.inputIndex;
+ const inputIndex = artifacts.get(clip.artifact.resource)!.inputIndex;
return audioClipFilter(clip, inputIndex, index);
});
const labels = plan.clips.map((_clip, index) => `[clip${index}]`).join("");
diff --git a/packages/media-execution/src/surface.ts b/packages/media-execution/src/surface.ts
index bca9e9aa..2e88a7a4 100644
--- a/packages/media-execution/src/surface.ts
+++ b/packages/media-execution/src/surface.ts
@@ -209,7 +209,7 @@ export async function verifyCompositableSurfaceBytes(options: {
}): Promise<void> {
assertCompositableSurfaceRef(options.surface);
assert(options.bytes.byteLength === options.surface.artifact.size,
- `Surface ${options.surface.artifact.digest} byte size differs`);
+ `Surface ${options.surface.artifact.resource} byte size differs`);
const ffprobePath = options.ffprobePath ?? "ffprobe";
const timeoutMs = options.processTimeoutMs ?? 120_000;
const maxOutputBytes = options.maxProbeOutputBytes ?? 8 * 1024 * 1024;
diff --git a/packages/media-execution/test/probe.test.ts b/packages/media-execution/test/probe.test.ts
index 4f17498b..2739b84d 100644
--- a/packages/media-execution/test/probe.test.ts
+++ b/packages/media-execution/test/probe.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { parseMediaInspection } from "@hypit/media-execution";
@@ -9,7 +9,7 @@ test("probe derives the last decoded-unit duration instead of adding whole-strea
const inspection = parseMediaInspection({
source: {
kind: "blob",
- digest: fixtureDigest("probe-duration-fixture"),
+ resource: fixtureResource("probe-duration-fixture"),
size: 1,
mediaType: "video/mp4",
},
@@ -59,7 +59,7 @@ test("probe derives the last decoded-unit duration instead of adding whole-strea
test("probe preserves square-pixel and quarter-turn facts needed before Spatial", () => {
const source = {
kind: "blob" as const,
- digest: fixtureDigest("probe-display-geometry-fixture"),
+ resource: fixtureResource("probe-display-geometry-fixture"),
size: 1,
mediaType: "video/mp4",
};
diff --git a/packages/media-execution/test/surface.test.ts b/packages/media-execution/test/surface.test.ts
index 6164fde4..2bd5b508 100644
--- a/packages/media-execution/test/surface.test.ts
+++ b/packages/media-execution/test/surface.test.ts
@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
import { spawn, spawnSync } from "node:child_process";
import { mkdtemp, readFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
@@ -26,6 +25,8 @@ async function ffmpeg(argv: readonly string[]): Promise<void> {
});
}
+let surfaceId = 0;
+
function surface(bytes: Uint8Array, options: {
readonly mediaType: string;
readonly width: number;
@@ -33,9 +34,9 @@ function surface(bytes: Uint8Array, options: {
readonly alphaMode: "opaque" | "straight";
readonly timing: CompositableSurfaceRef["timing"];
}): CompositableSurfaceRef {
- const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}` as const;
+ const resource = `res_surface-${surfaceId += 1}` as const;
return {
- artifact: { kind: "blob", digest, size: bytes.byteLength, mediaType: options.mediaType },
+ artifact: { kind: "blob", resource, size: bytes.byteLength, mediaType: options.mediaType },
width: options.width,
height: options.height,
colorSpace: "srgb",
diff --git a/packages/media-pipeline/src/audio-plan.ts b/packages/media-pipeline/src/audio-plan.ts
index 918379a1..a7bbaa52 100644
--- a/packages/media-pipeline/src/audio-plan.ts
+++ b/packages/media-pipeline/src/audio-plan.ts
@@ -2,7 +2,7 @@ import { programFrameSampleBoundary, programSpaceFrameCount } from "@hypit/progr
import type { ProgramSpace } from "@hypit/program-space";
import { assertCompositionIdentity } from "@hypit/composition";
import type { Composition } from "@hypit/composition";
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import type { AudioProgramPlan } from "./types.js";
@@ -36,7 +36,7 @@ export function verifyAudioProgramPlan(value: unknown): asserts value is AudioPr
assert(typeof clip.id === "string" && clip.id.length > 0 && !ids.has(clip.id),
"AudioProgramPlan clip id is empty or repeated");
ids.add(clip.id);
- assert(clip.artifact?.kind === "blob" && isDigest(clip.artifact.digest)
+ assert(clip.artifact?.kind === "blob" && isResourceId(clip.artifact.resource)
&& Number.isSafeInteger(clip.artifact.size) && clip.artifact.size >= 0
&& clip.artifact.mediaType === "audio/wav",
`AudioProgramPlan clip ${clip.id} must reference canonical WAV`);
@@ -85,7 +85,7 @@ export function compileAudioProgramPlan(composition: Composition, programSpace:
id: `${track.id}:${clip.id}`,
artifact: {
kind: "blob" as const,
- digest: clip.artifact.digest,
+ resource: clip.artifact.resource,
size: clip.artifact.size,
mediaType: clip.artifact.mediaType,
},
diff --git a/packages/media-pipeline/src/manifest.ts b/packages/media-pipeline/src/manifest.ts
index e0809025..d2fe1df6 100644
--- a/packages/media-pipeline/src/manifest.ts
+++ b/packages/media-pipeline/src/manifest.ts
@@ -175,7 +175,7 @@ const blobRefSchema: ValueSchema = {
kind: "object",
fields: {
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
size: { schema: { kind: "number", integer: true, minimum: 0 } },
mediaType: { schema: { kind: "literal", value: "audio/wav" } },
},
diff --git a/packages/media-pipeline/src/types.ts b/packages/media-pipeline/src/types.ts
index 8c9c0acd..6773b4e6 100644
--- a/packages/media-pipeline/src/types.ts
+++ b/packages/media-pipeline/src/types.ts
@@ -138,7 +138,7 @@ export type AudioProgramClip = {
readonly fadeOutSamples: number;
};
-/** Pure, content-addressed plan. Executing it is always a Provider Need. */
+/** Pure media plan. Executing it is always a Provider Need. */
export type AudioProgramPlan = {
readonly frameRate: MediaRational;
readonly frameCount: number;
diff --git a/packages/media-pipeline/test/selection.test.ts b/packages/media-pipeline/test/selection.test.ts
index b0f797aa..2a5af49d 100644
--- a/packages/media-pipeline/test/selection.test.ts
+++ b/packages/media-pipeline/test/selection.test.ts
@@ -2,7 +2,7 @@ import { sealMediaInspection, verifyMediaStreamSelection } from "@hypit/media";
import type { MediaInspection, MediaVideoStream } from "@hypit/media";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
@@ -12,7 +12,7 @@ import {
const source = {
kind: "blob" as const,
- digest: fixtureDigest("grok-container"),
+ resource: fixtureResource("grok-container"),
size: 123,
mediaType: "video/mp4",
};
@@ -92,7 +92,7 @@ test("primary stream selection excludes Grok's MJPEG attached picture and observ
assert.equal(selection.videoStreamIndex, 0);
assert.equal(selection.audioStreamIndex, 1);
assert.equal(selection.spanAuthority, "video");
- assert.equal("basisDigest" in selection, false);
+ assert.equal("basisResourceId" in selection, false);
assert.equal("narrativeDigest" in selection, false);
});
diff --git a/packages/media-track-studio/src/index.ts b/packages/media-track-studio/src/index.ts
index c5601557..4d5a53c0 100644
--- a/packages/media-track-studio/src/index.ts
+++ b/packages/media-track-studio/src/index.ts
@@ -107,10 +107,10 @@ function materialPreview(
if (layer?.kind !== "sample") return undefined;
if (facet === "audio") {
const artifact = layer.source.kind === "timed" ? layer.source.audio?.artifact : undefined;
- return artifact === undefined ? undefined : artifactPreview("audio", artifact.digest);
+ return artifact === undefined ? undefined : artifactPreview("audio", artifact.resource);
}
if (layer.source.kind === "surface") return undefined;
- return artifactPreview(layer.source.kind === "still" ? "image" : "video", layer.source.artifact.digest);
+ return artifactPreview(layer.source.kind === "still" ? "image" : "video", layer.source.artifact.resource);
}
function projectMedia(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
diff --git a/packages/media-track/src/layers.ts b/packages/media-track/src/layers.ts
index d6805dbd..8792877f 100644
--- a/packages/media-track/src/layers.ts
+++ b/packages/media-track/src/layers.ts
@@ -4,7 +4,7 @@ import {
verifySynchronizedMedia,
} from "@hypit/media";
import type { CompositableSurfaceRef, SynchronizedMedia } from "@hypit/media";
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
import {
assertContentFit,
@@ -35,7 +35,7 @@ export function assertMediaIdentity(value: string, label: string): void {
}
function assertBlob(value: BlobRef, label: string, prefix?: string): void {
- assert(value.kind === "blob" && isDigest(value.digest)
+ assert(value.kind === "blob" && isResourceId(value.resource)
&& Number.isSafeInteger(value.size) && value.size >= 0 && value.mediaType.length > 0,
`${label} is not a valid BlobArtifact.`);
if (prefix !== undefined) assert(value.mediaType.startsWith(prefix), `${label} must be ${prefix} bytes.`);
diff --git a/packages/media-track/src/manifest.ts b/packages/media-track/src/manifest.ts
index 6263ed03..47aa46ec 100644
--- a/packages/media-track/src/manifest.ts
+++ b/packages/media-track/src/manifest.ts
@@ -74,7 +74,7 @@ const positiveInteger = { kind: "number", integer: true, minimum: 1 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
const blob = object({
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
size: { schema: unsignedInteger },
mediaType: { schema: string },
});
diff --git a/packages/media-track/src/program.ts b/packages/media-track/src/program.ts
index e891f710..5ea4cbae 100644
--- a/packages/media-track/src/program.ts
+++ b/packages/media-track/src/program.ts
@@ -12,7 +12,7 @@ import {
programSpaceSampleFrames,
} from "@hypit/program-space";
import type { ProgramSpace } from "@hypit/program-space";
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
import type { CanvasSpace } from "@hypit/spatial";
import { assertSpatialPath } from "@hypit/spatial";
@@ -82,7 +82,7 @@ function finite(value: number, label: string): void {
}
function assertSound(value: MediaSoundSource, label: string): void {
- assert(value.artifact.kind === "blob" && isDigest(value.artifact.digest)
+ assert(value.artifact.kind === "blob" && isResourceId(value.artifact.resource)
&& value.artifact.mediaType.startsWith("audio/")
&& Number.isSafeInteger(value.artifact.size) && value.artifact.size >= 0
&& Number.isSafeInteger(value.sampleFrames) && value.sampleFrames > 0, `${label} is invalid.`);
diff --git a/packages/media-track/test/media-track.test.ts b/packages/media-track/test/media-track.test.ts
index ab5326e7..04578df0 100644
--- a/packages/media-track/test/media-track.test.ts
+++ b/packages/media-track/test/media-track.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import { projectMomentWindow, projectProgramWindow, projectSegmentWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";
import type { TemporalWindowProjection } from "../../../test/temporal-fixture.js";
@@ -89,7 +89,7 @@ const semantic = semanticTrackFixture(space, {
});
const source: BlobRef = {
kind: "blob",
- digest: fixtureDigest("media-track:still"),
+ resource: fixtureResource("media-track:still"),
size: 4_096,
mediaType: "image/png",
};
@@ -199,12 +199,12 @@ function timed(id = "timed", withAudio = true): SynchronizedMedia {
frameCount: 60,
},
visual: {
- artifact: { kind: "blob", digest: fixtureDigest(`video:${id}`), size: 10_000, mediaType: "video/mp4" },
+ artifact: { kind: "blob", resource: fixtureResource(`video:${id}`), size: 10_000, mediaType: "video/mp4" },
width: 720,
height: 1280,
},
...(withAudio ? { audio: {
- artifact: { kind: "blob" as const, digest: fixtureDigest(`audio:${id}`), size: sampleFrames * 4, mediaType: "audio/wav" },
+ artifact: { kind: "blob" as const, resource: fixtureResource(`audio:${id}`), size: sampleFrames * 4, mediaType: "audio/wav" },
} } : {}),
};
}
@@ -363,7 +363,7 @@ test("an owned clip path is an explicit Media input and lowers only over the Ite
'path("M 0 0 L 400 0 L 360 300 L 40 300 Z")');
});
-test("self-blur is two explicit samples of one Artifact and Artifact collection deduplicates bytes", () => {
+test("self-blur is two explicit samples of one Resource and collection keeps one reference", () => {
let layers = createMediaLayerSet();
layers = appendStillMediaLayer(layers, source, extent, { ...fit, sizing: "cover" }, sealMediaSampleLayerSpec({
id: "blurred", appearance: {
@@ -382,9 +382,9 @@ test("self-blur is two explicit samples of one Artifact and Artifact collection
tracks: [track],
}), space);
assert.equal(document.artifacts.length, 1);
- assert.equal((document.html.match(new RegExp(source.digest, "gu")) ?? []).length, 0,
- "HTML uses artifact URIs without the digest prefix spelling");
- assert.equal((document.html.match(/hypit-artifact:\/\/sha256\//gu) ?? []).length, 2);
+ assert.equal((document.html.match(new RegExp(source.resource, "gu")) ?? []).length, 2,
+ "HTML names the same declared Resource at both sampling sites");
+ assert.equal((document.html.match(/hypit-resource:\/\/res_/gu) ?? []).length, 2);
const blurred = track.presents[0]!.elements.find((element) => element.id === "blurred");
assert.equal(blurred?.style.find((entry) => entry.name === "left")?.value, "-48px");
assert.equal(blurred?.style.find((entry) => entry.name === "top")?.value, "-48px");
@@ -505,7 +505,7 @@ test("source audio and edge SFX project separately from the visual Track", () =>
test("still and animated typed Surfaces use the same layer law without browser format guesses", () => {
const still: CompositableSurfaceRef = {
- artifact: { kind: "blob", digest: fixtureDigest("surface:still"), size: 500, mediaType: "image/png" },
+ artifact: { kind: "blob", resource: fixtureResource("surface:still"), size: 500, mediaType: "image/png" },
width: 100,
height: 100,
colorSpace: "srgb",
@@ -514,7 +514,7 @@ test("still and animated typed Surfaces use the same layer law without browser f
};
const animated: CompositableSurfaceRef = {
...still,
- artifact: { kind: "blob", digest: fixtureDigest("surface:animated"), size: 2_000, mediaType: "video/webm" },
+ artifact: { kind: "blob", resource: fixtureResource("surface:animated"), size: 2_000, mediaType: "video/webm" },
timing: { kind: "frames", frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },
};
let layers = appendSurfaceMediaLayer(createMediaLayerSet(), still, fit, sealMediaSampleLayerSpec({
@@ -643,7 +643,7 @@ test("every documented Media frame and fit remains one ordinary Item instead of
});
test("transparent, Paint, self-blur and alternate-source backing are only ordered owned layers", () => {
- const alternate: BlobRef = { kind: "blob", digest: fixtureDigest("media-track:alternate"), size: 2_048, mediaType: "image/webp" };
+ const alternate: BlobRef = { kind: "blob", resource: fixtureResource("media-track:alternate"), size: 2_048, mediaType: "image/webp" };
let layers = createMediaLayerSet();
layers = appendMediaPaintLayer(layers, sealMediaPaintLayerSpec({
id: "solid", paint: { kind: "solid", color: "#101018" }, opacity: 1,
@@ -849,7 +849,7 @@ test("Sequence resolves strict logical phases, expanded handoffs and one uninter
test("Sequence handoffs accept still, timed and alpha Surface members through one lowering path", () => {
const alphaSurface: CompositableSurfaceRef = {
- artifact: { kind: "blob", digest: fixtureDigest("surface:alpha-member"), size: 800, mediaType: "image/png" },
+ artifact: { kind: "blob", resource: fixtureResource("surface:alpha-member"), size: 800, mediaType: "image/png" },
width: 200, height: 300, colorSpace: "srgb", alphaMode: "straight", timing: { kind: "still" },
};
const surfaceLayers = () => appendSurfaceMediaLayer(createMediaLayerSet(), alphaSurface, fit, sealMediaSampleLayerSpec({
diff --git a/packages/media/README.md b/packages/media/README.md
index be864467..04e42065 100644
--- a/packages/media/README.md
+++ b/packages/media/README.md
@@ -3,7 +3,7 @@
Author-facing media declarations for the neutral `@hypit/media` contract module.
`<media:Image>`, `<media:Audio>`, `<media:Video>` and `<media:Font>` request bytes through the Host-owned source-asset
-capability. Image, Audio and Video emit one content-addressed `BlobArtifact`; Font wraps the same immutable
+capability. Image, Audio and Video emit one Resource-backed `BlobArtifact`; Font wraps the same immutable
bytes with exact weight/style metadata as a one-source `FontArtifactRef`. A logical font face may
also contain several exact Unicode-range sources when another package, such as
`@hypit/fonts-open`, owns a sharded installed font. `FontStackRef` is the generic ordered value
diff --git a/packages/media/src/identity.ts b/packages/media/src/identity.ts
index 4c5381de..dca1f04c 100644
--- a/packages/media/src/identity.ts
+++ b/packages/media/src/identity.ts
@@ -1,6 +1,6 @@
import {
canonicalize,
- isDigest,
+ isResourceId,
} from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
@@ -59,7 +59,7 @@ function compareTimestamp(left: MediaTimestamp, right: MediaTimestamp): number {
function verifyBlob(value: unknown, subject: string): asserts value is BlobRef {
const item = object(value, subject);
assert(item.kind === "blob", `${subject} must be a BlobRef`);
- assert(typeof item.digest === "string" && isDigest(item.digest), `${subject}.digest is invalid`);
+ assert(typeof item.resource === "string" && isResourceId(item.resource), `${subject}.resource is invalid`);
nonNegativeInteger(item.size, `${subject}.size`);
assert(typeof item.mediaType === "string" && item.mediaType.length > 0, `${subject}.mediaType is invalid`);
}
diff --git a/packages/media/src/manifest.ts b/packages/media/src/manifest.ts
index e3a33f24..243cd85a 100644
--- a/packages/media/src/manifest.ts
+++ b/packages/media/src/manifest.ts
@@ -17,7 +17,7 @@ export const mediaMarkupSurfaces = [
{
name: "image", tag: "Image", mode: "structured", outputs: [artifactTypes.blob],
vocabulary: {
- summary: "Requests one authored image file from the Host and publishes it as a content-addressed Artifact.",
+ summary: "Requests one authored image file from the Host and publishes it as a byte Artifact.",
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the Artifact Record this element publishes." },
@@ -38,7 +38,7 @@ export const mediaMarkupSurfaces = [
{
name: "audio", tag: "Audio", mode: "structured", outputs: [artifactTypes.blob],
vocabulary: {
- summary: "Requests one authored audio file from the Host and publishes it as a content-addressed Artifact.",
+ summary: "Requests one authored audio file from the Host and publishes it as a byte Artifact.",
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the Artifact Record this element publishes." },
@@ -59,7 +59,7 @@ export const mediaMarkupSurfaces = [
{
name: "video", tag: "Video", mode: "structured", outputs: [artifactTypes.blob],
vocabulary: {
- summary: "Requests one authored video file from the Host and publishes it as a content-addressed Artifact.",
+ summary: "Requests one authored video file from the Host and publishes it as a byte Artifact.",
attributes: [
{ name: "id", kind: "identifier", required: true,
summary: "Names the Artifact Record this element publishes." },
diff --git a/packages/media/src/render.ts b/packages/media/src/render.ts
index 52a8fa84..22d0cc0e 100644
--- a/packages/media/src/render.ts
+++ b/packages/media/src/render.ts
@@ -1,4 +1,4 @@
-import { isDigest } from "@hypit/protocol";
+import { isResourceId } from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
const FONT_MEDIA_TYPES = new Set([
@@ -50,7 +50,7 @@ export type CompositableSurfaceRef = {
function assertBlobRef(value: BlobRef, label: string): void {
if (
value.kind !== "blob"
- || !isDigest(value.digest)
+ || !isResourceId(value.resource)
|| !Number.isSafeInteger(value.size)
|| value.size < 0
|| !value.mediaType
@@ -67,8 +67,8 @@ export function assertFontArtifactRef(value: FontArtifactRef, label = "FontArtif
if (!FONT_MEDIA_TYPES.has(source.artifact.mediaType)) {
throw new Error(`${label}.sources.${index} Artifact must use a supported font media type.`);
}
- if (artifacts.has(source.artifact.digest)) throw new Error(`${label} repeats a source Artifact.`);
- artifacts.add(source.artifact.digest);
+ if (artifacts.has(source.artifact.resource)) throw new Error(`${label} repeats a source Artifact.`);
+ artifacts.add(source.artifact.resource);
if (source.unicodeRange !== undefined
&& !/^U\+[0-9a-f?]{1,6}(?:-[0-9a-f]{1,6})?(?:,U\+[0-9a-f?]{1,6}(?:-[0-9a-f]{1,6})?)*$/iu.test(source.unicodeRange)) {
throw new Error(`${label}.sources.${index} Unicode range is invalid.`);
@@ -88,7 +88,7 @@ export function assertFontStackRef(value: FontStackRef, label = "FontStackRef"):
for (const [index, face] of value.faces.entries()) {
assertFontArtifactRef(face, `${label}.faces.${index}`);
const identity = JSON.stringify({
- sources: face.sources.map((source) => [source.artifact.digest, source.unicodeRange ?? null]),
+ sources: face.sources.map((source) => [source.artifact.resource, source.unicodeRange ?? null]),
weight: face.weight,
style: face.style,
});
diff --git a/packages/media/src/schema.ts b/packages/media/src/schema.ts
index 3d0b4de4..10a7ebed 100644
--- a/packages/media/src/schema.ts
+++ b/packages/media/src/schema.ts
@@ -3,17 +3,15 @@ const string = { kind: "string", minLength: 1 } as const;
const number = { kind: "number", minimum: 0 } as const;
const seconds = { kind: "number", minimum: 0 } as const;
const integer = { kind: "number", integer: true, minimum: 0 } as const;
-// Structural admission fixes the length; media Type validators prove the
-// content-addressed identity wherever the value carries semantic media truth.
-const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
const blobArtifactSchema = (mediaTypes?: readonly string[]): ValueSchema => object({
- kind: { schema: { kind: "literal", value: "blob" } }, resource: { schema: string, optional: true },
+ kind: { schema: { kind: "literal", value: "blob" } },
+ resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
origin: { schema: object({
kind: { schema: { kind: "literal", value: "build-file" } },
build: { schema: string }, path: { schema: string },
}), optional: true },
- digest: { schema: digest }, size: { schema: integer },
+ size: { schema: integer },
mediaType: { schema: mediaTypes === undefined ? string : { kind: "string", enum: mediaTypes } },
});
const rational = object({ numerator: { schema: { kind: "number", integer: true, minimum: 1 } }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } });
diff --git a/packages/media/src/types.ts b/packages/media/src/types.ts
index a70e7c7c..d6fecb64 100644
--- a/packages/media/src/types.ts
+++ b/packages/media/src/types.ts
@@ -57,7 +57,7 @@ export type MediaOtherStream = MediaStreamBase & {
export type MediaStream = MediaVideoStream | MediaAudioStream | MediaOtherStream;
-/** Immutable observed facts about one exact content-addressed container. */
+/** Immutable observed facts about one exact media container. */
export type MediaInspection = {
readonly container: {
readonly formatNames: readonly string[];
diff --git a/packages/media/test/asset-surface.test.ts b/packages/media/test/asset-surface.test.ts
index 63ca0653..40b0f61e 100644
--- a/packages/media/test/asset-surface.test.ts
+++ b/packages/media/test/asset-surface.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
decodeMediaAudioSurface,
@@ -18,7 +18,7 @@ for (const fixture of [
test(`${fixture.label} Surface publishes the resolved BlobArtifact`, async () => {
const artifact = {
kind: "blob" as const,
- digest: fixtureDigest(`media:${fixture.label.toLowerCase()}`),
+ resource: fixtureResource(`media:${fixture.label.toLowerCase()}`),
size: 2_048,
mediaType: fixture.mediaType,
};
@@ -52,7 +52,7 @@ test("Video Surface rejects ambiguous extensions and non-video resolved artifact
element: { kind: "element", name: "media:Video", attributes, children: [], range },
resolveReference: () => undefined,
resolveAsset: (request) => ({ artifact: {
- kind: "blob", digest: fixtureDigest("media:video-invalid"), size: 10, mediaType,
+ kind: "blob", resource: fixtureResource("media:video-invalid"), size: 10, mediaType,
} }),
});
diff --git a/packages/media/test/font-surface.test.ts b/packages/media/test/font-surface.test.ts
index a06ec054..ccfa4768 100644
--- a/packages/media/test/font-surface.test.ts
+++ b/packages/media/test/font-surface.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { decodeMediaFontSurface, mediaTypes } from "@hypit/media";
@@ -23,7 +23,7 @@ test("Font Surface turns explicit author bytes and face metadata into one exact
return {
artifact: {
kind: "blob",
- digest: fixtureDigest("font:inter-bold"),
+ resource: fixtureResource("font:inter-bold"),
size: 2_048,
mediaType: request.mediaType,
},
@@ -39,7 +39,7 @@ test("Font Surface turns explicit author bytes and face metadata into one exact
value: {
sources: [{ artifact: {
kind: "blob",
- digest: fixtureDigest("font:inter-bold"),
+ resource: fixtureResource("font:inter-bold"),
size: 2_048,
mediaType: "font/woff2",
} }],
diff --git a/packages/mock-media/README.md b/packages/mock-media/README.md
index ea2e4d33..ad857792 100644
--- a/packages/mock-media/README.md
+++ b/packages/mock-media/README.md
@@ -2,4 +2,4 @@
Preview-only mock media Fragments and their `render-mock-image`, `render-mock-video`, and
`render-mock-silence` capability contracts. The local Provider executes these capabilities into
-ordinary content-addressed `BlobArtifact` values; no mock type or user Source is introduced.
+ordinary Resource-backed `BlobArtifact` values; no mock type or user Source is introduced.
diff --git a/packages/model-kit/test/model-kit.test.ts b/packages/model-kit/test/model-kit.test.ts
index a61527d2..bdf23a85 100644
--- a/packages/model-kit/test/model-kit.test.ts
+++ b/packages/model-kit/test/model-kit.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
sealGenerationMediaBinding,
@@ -42,7 +42,7 @@ test("one exact model definition owns draft, media binding, finalization and gen
const artifact = {
kind: "blob" as const,
- digest: fixtureDigest("graph-native-image"),
+ resource: fixtureResource("graph-native-image"),
size: 4,
mediaType: "image/png",
};
diff --git a/packages/preview-mock/package.json b/packages/preview-mock/package.json
index 126d6da3..61abc037 100644
--- a/packages/preview-mock/package.json
+++ b/packages/preview-mock/package.json
@@ -8,7 +8,7 @@
"hypit": { "activation": "./src/activation.ts" },
"dependencies": {
"@hypit/artifact": "workspace:*",
- "@hypit/artifact-store-fs": "workspace:*",
+ "@hypit/resource-store-fs": "workspace:*",
"@hypit/compiler-node": "workspace:*",
"@hypit/estimate": "workspace:*",
"@hypit/driver-node": "workspace:*",
diff --git a/packages/preview-mock/src/materialize.ts b/packages/preview-mock/src/materialize.ts
index 989b1ee9..785a78d3 100644
--- a/packages/preview-mock/src/materialize.ts
+++ b/packages/preview-mock/src/materialize.ts
@@ -1,31 +1,32 @@
import type { ArtifactAttachment } from "@hypit/workspace";
import type { BlobRef } from "@hypit/protocol";
-import { MemoryArtifactStore, EndpointRegistry } from "@hypit/driver-node";
+import { MemoryResourceStore, EndpointRegistry } from "@hypit/driver-node";
import { createLocalMediaProvider } from "@hypit/provider-media-local";
import { mockMediaCapabilities } from "@hypit/mock-media";
-type ArtifactStore = {
- readonly get: (digest: BlobRef["digest"]) => Promise<Uint8Array | undefined>;
+type ResourceStore = {
+ readonly get: (resource: BlobRef["resource"]) => Promise<Uint8Array | undefined>;
readonly put: (bytes: Uint8Array, mediaType: string) => Promise<BlobRef>;
- readonly has: (digest: BlobRef["digest"]) => Promise<boolean>;
+ readonly write: (resource: BlobRef, bytes: Uint8Array) => Promise<void>;
+ readonly has: (resource: BlobRef["resource"]) => Promise<boolean>;
};
/**
* Execute one mock Need with the local Provider. Callers may provide the
- * project preview ArtifactStore so the resulting bytes survive the process
+ * project preview ResourceStore so the resulting bytes survive the process
* which created the temporary Run (Studio is deliberately a separate
* process). The in-memory default is retained for small library callers.
*/
export async function materializeMockNeed(input: {
readonly capability: typeof mockMediaCapabilities[keyof typeof mockMediaCapabilities];
readonly constraints: unknown;
- readonly artifacts?: ArtifactStore;
+ readonly resources?: ResourceStore;
}): Promise<{ readonly artifact: BlobRef; readonly attachment: ArtifactAttachment }> {
- const artifacts = input.artifacts ?? new MemoryArtifactStore();
+ const resources = input.resources ?? new MemoryResourceStore();
const registry = new EndpointRegistry();
await createLocalMediaProvider({}).install(registry);
const registration = registry.resolve({ id: "mock", capability: input.capability, returns: { module: { name: "@hypit/artifact", version: "1" }, name: "BlobArtifact" }, constraints: input.constraints as never, result: "mock" });
if (registration.status !== "resolved" || registration.registration.kind !== "immediate") throw new Error(`No local mock capability configured for ${input.capability.name}`);
- const result = await registration.registration.handler({ command: { kind: "fulfill-need", id: "mock", need: { id: "mock", capability: input.capability, returns: registration.registration.returns, constraints: input.constraints as never, result: "mock" } }, need: { id: "mock", capability: input.capability, returns: registration.registration.returns, constraints: input.constraints as never, result: "mock" }, artifacts, credentials: {} });
+ const result = await registration.registration.handler({ command: { kind: "fulfill-need", id: "mock", need: { id: "mock", capability: input.capability, returns: registration.registration.returns, constraints: input.constraints as never, result: "mock" } }, need: { id: "mock", capability: input.capability, returns: registration.registration.returns, constraints: input.constraints as never, result: "mock" }, resources, credentials: {} });
if (result.value.kind !== "blob") throw new Error("Mock Provider returned a non-Artifact value");
const artifact = result.value;
return {
@@ -33,7 +34,7 @@ export async function materializeMockNeed(input: {
attachment: {
artifact,
open: async () => (async function* () {
- const bytes = await artifacts.get(artifact.digest);
+ const bytes = await resources.get(artifact.resource);
if (bytes !== undefined) yield bytes;
})(),
},
diff --git a/packages/preview-mock/src/realizer.ts b/packages/preview-mock/src/realizer.ts
index 1e82e0d9..3d5ce3b2 100644
--- a/packages/preview-mock/src/realizer.ts
+++ b/packages/preview-mock/src/realizer.ts
@@ -1,6 +1,5 @@
-import { createHash } from "node:crypto";
import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
import type { ArtifactAttachment } from "@hypit/workspace";
import type { CompiledGraph, TypedRecord } from "@hypit/protocol";
import { estimatedProgramDurationSeconds, findMockTargets } from "./graph.js";
@@ -8,7 +7,7 @@ import { deriveGeometry } from "./geometry.js";
import { previewRunSource } from "./run-source.js";
import { materializeMockNeed } from "./materialize.js";
import { mockMediaCapabilities } from "@hypit/mock-media";
-import { FileArtifactStore } from "@hypit/artifact-store-fs";
+import { FileResourceStore } from "@hypit/resource-store-fs";
export type PreviewMockTiming = "estimate";
export type PreviewMockRequest = { readonly run: string; readonly targets?: readonly string[]; readonly timing?: PreviewMockTiming; readonly cacheRoot?: string; readonly graph?: CompiledGraph; readonly records?: readonly TypedRecord[]; readonly author?: string; readonly aliases?: ReadonlyMap<string, string> };
@@ -24,8 +23,13 @@ export type PreviewMockResult = {
readonly timingBasis: "estimate";
};
-function artifactRelativePath(root: string, digest: string): string {
- return `./artifacts/sha256/${digest.split(":")[1]!.slice(0, 2)}/${digest.split(":")[1]!}`;
+function artifactRelativePath(root: string, resource: string): string {
+ return `./artifacts/resources/${resource}`;
+}
+
+function previewDirectoryName(run: string): string {
+ const name = basename(run).replace(/[^a-zA-Z0-9._-]+/gu, "-");
+ return name.length === 0 ? "run" : name;
}
export async function realizePreviewMock(input: PreviewMockRequest): Promise<PreviewMockResult> {
@@ -34,7 +38,7 @@ export async function realizePreviewMock(input: PreviewMockRequest): Promise<Pre
const author = input.author ?? /<author\s+source="([^"]+)"/u.exec(source)?.[1];
if (author === undefined) throw new Error(`${input.run} declares no author source`);
if (input.graph === undefined) {
- const root = input.cacheRoot ?? join(dirname(run), ".hypit", "preview", createHash("sha256").update(source).digest("hex").slice(0, 16));
+ const root = input.cacheRoot ?? join(dirname(run), ".hypit", "preview", previewDirectoryName(run));
await mkdir(root, { recursive: true });
const previewRun = join(root, "preview.svrun");
const mockRun = join(root, "mock.svrun");
@@ -53,19 +57,12 @@ export async function realizePreviewMock(input: PreviewMockRequest): Promise<Pre
const selectedTargets = (input.targets ?? input.graph.outputs.map((item) => item.id)).map(alias);
const geometry = deriveGeometry(input.graph, rawTargets.map((item) => item.output));
const authorPath = resolve(dirname(run), author);
- const authorSource = await readFile(authorPath, "utf8");
- const root = input.cacheRoot ?? join(dirname(run), ".hypit", "preview", createHash("sha256")
- .update(JSON.stringify({
- authorDigest: createHash("sha256").update(authorSource).digest("hex"),
- runDigest: createHash("sha256").update(source).digest("hex"),
- targets: rawTargets.map((item) => item.output).sort(),
- geometry,
- timing: input.timing ?? "estimate",
- })).digest("hex").slice(0, 16));
+ await readFile(authorPath, "utf8");
+ const root = input.cacheRoot ?? join(dirname(run), ".hypit", "preview", previewDirectoryName(run));
await mkdir(root, { recursive: true });
const previewRun = join(root, "preview.svrun");
const mockRun = join(root, "mock.svrun");
- const artifactStore = new FileArtifactStore(join(root, "artifacts"));
+ const resourceStore = new FileResourceStore(join(root, "artifacts"));
const preserved = [...source.matchAll(/^\s*<(?:file|value|build-record)\b[^>]*\/?>(?:\s*)$/gmu)]
.map((match) => (match[0] ?? "").trim())
.map((line) => line.replace(/\bfrom="([^"]+)"/u, (_whole, from: string) => {
@@ -78,7 +75,7 @@ export async function realizePreviewMock(input: PreviewMockRequest): Promise<Pre
}));
// Keep the native mock Run as a durable audit/debug artifact. Its Needs are
// fulfilled by the local mock Provider below; Studio then opens the second
- // Run, whose relative file Candidates point at those content-addressed
+ // Run, whose relative file Candidates point at those persisted
// results and therefore require no Provider endpoint.
const generatedMock = previewRunSource(resolve(dirname(run), author), mockRun, selectedTargets, geometry, targets);
await writeFile(mockRun, generatedMock, "utf8");
@@ -108,15 +105,15 @@ export async function realizePreviewMock(input: PreviewMockRequest): Promise<Pre
audio: "silence",
}
: { sampleRate: 48_000, channels: 2, sampleFrames: 48_000 };
- const materialized = await materializeMockNeed({ capability, constraints, artifacts: artifactStore });
- if (!attached.has(materialized.artifact.digest)) {
- attached.add(materialized.artifact.digest);
+ const materialized = await materializeMockNeed({ capability, constraints, resources: resourceStore });
+ if (!attached.has(materialized.artifact.resource)) {
+ attached.add(materialized.artifact.resource);
attachments.push(materialized.attachment);
}
const candidateId = `mock-file-${files.size}`;
files.set(target.output, {
id: candidateId,
- from: artifactRelativePath(root, materialized.artifact.digest),
+ from: artifactRelativePath(root, materialized.artifact.resource),
mediaType: materialized.artifact.mediaType,
});
}
diff --git a/packages/protocol/src/canonical.ts b/packages/protocol/src/canonical.ts
index 1a5d895f..6a060cf1 100644
--- a/packages/protocol/src/canonical.ts
+++ b/packages/protocol/src/canonical.ts
@@ -1,5 +1,5 @@
import { SvmlError } from "./error.js";
-import type { Digest } from "./identity.js";
+import type { ResourceId } from "./identity.js";
import type { CanonicalValue } from "./value.js";
function normalize(value: unknown, path: string): CanonicalValue {
@@ -32,6 +32,6 @@ export function canonicalStringify(value: unknown): string {
return JSON.stringify(canonicalize(value));
}
-export function isDigest(value: string): value is Digest {
- return /^sha256:[0-9a-f]{64}$/u.test(value);
+export function isResourceId(value: string): value is ResourceId {
+ return /^res_[a-zA-Z0-9._:-]+$/u.test(value);
}
diff --git a/packages/protocol/src/identity.ts b/packages/protocol/src/identity.ts
index 38a0f2d3..22ea4330 100644
--- a/packages/protocol/src/identity.ts
+++ b/packages/protocol/src/identity.ts
@@ -1,4 +1,5 @@
-export type Digest = `sha256:${string}`;
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+export type ResourceId = `res_${string}`;
export type RecordId = string;
export type LogicalOutputId = string;
diff --git a/packages/protocol/src/value.ts b/packages/protocol/src/value.ts
index 446a5fe5..935b69aa 100644
--- a/packages/protocol/src/value.ts
+++ b/packages/protocol/src/value.ts
@@ -1,4 +1,4 @@
-import type { Digest } from "./identity.js";
+import type { ResourceId } from "./identity.js";
export type CanonicalValue =
| null
@@ -10,15 +10,14 @@ export type CanonicalValue =
export type BlobRef = {
readonly kind: "blob";
- /** One admitted resource instance. Unlike digest, equal bytes admitted twice keep distinct identities. */
- readonly resource?: string;
+ /** One admitted resource instance. Equal bytes admitted twice keep distinct identities. */
+ readonly resource: ResourceId;
/** Exact durable origin carried only when a historical Build file enters a new execution. */
readonly origin?: {
readonly kind: "build-file";
readonly build: string;
readonly path: string;
};
- readonly digest: Digest;
readonly size: number;
readonly mediaType: string;
};
@@ -83,7 +82,7 @@ export function blobRefObjectSchema(mediaTypes?: readonly string[]): ValueSchema
kind: "object",
fields: {
kind: { schema: { kind: "literal", value: "blob" } },
- resource: { schema: { kind: "string", minLength: 1 }, optional: true },
+ resource: { schema: { kind: "string", minLength: 5 } },
origin: {
schema: {
kind: "object",
@@ -95,7 +94,6 @@ export function blobRefObjectSchema(mediaTypes?: readonly string[]): ValueSchema
},
optional: true,
},
- digest: { schema: { kind: "string", minLength: 71, maxLength: 71 } },
size: { schema: { kind: "number", integer: true, minimum: 0 } },
mediaType: {
schema: mediaTypes === undefined
diff --git a/packages/protocol/test/canonical.test.ts b/packages/protocol/test/canonical.test.ts
index 067547c2..086930ac 100644
--- a/packages/protocol/test/canonical.test.ts
+++ b/packages/protocol/test/canonical.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { canonicalize, canonicalStringify, isDigest } from "@hypit/protocol";
+import { canonicalize, canonicalStringify, isResourceId } from "@hypit/protocol";
test("canonical values have stable key order and preserve array order", () => {
assert.equal(canonicalStringify({ b: 1, a: 2 }), '{"a":2,"b":1}');
@@ -19,8 +19,8 @@ test("values without one JSON meaning are refused", () => {
assert.throws(() => canonicalize({ a: undefined }), /is undefined/u);
});
-test("Blob digests retain their narrow byte-address syntax", () => {
- assert.equal(isDigest(`sha256:${"a".repeat(64)}`), true);
- assert.equal(isDigest("sha256:"), false);
- assert.equal(isDigest("md5:abc"), false);
+test("Resource ids retain their narrow execution-reference syntax", () => {
+ assert.equal(isResourceId("res_fixture-resource"), true);
+ assert.equal(isResourceId("fixture-resource"), false);
+ assert.equal(isResourceId("md5:abc"), false);
});
diff --git a/packages/provider-hyperframes-aws-lambda/README.md b/packages/provider-hyperframes-aws-lambda/README.md
index 6f0f6e03..2581d3bd 100644
--- a/packages/provider-hyperframes-aws-lambda/README.md
+++ b/packages/provider-hyperframes-aws-lambda/README.md
@@ -4,7 +4,7 @@ Asynchronous AWS Step Functions/Lambda implementation of the exact
`@hypit/render-hyperframes#render-visual` capability.
The Endpoint stages the immutable `HyperframesDocument` with the shared
-`stageHyperframesProject()` layout, uploads that content-addressed site, starts one distributed
+`stageHyperframesProject()` layout, uploads that operation-scoped site, starts one distributed
render and persists its execution ARN in the Operation checkpoint. Its Step Functions execution name is derived from the
Runtime Operation id, so recovery cannot accidentally submit the same attempt twice.
Cancellation uses that same identity to stop the remote Step Functions execution, including the
diff --git a/packages/provider-hyperframes-aws-lambda/src/provider.ts b/packages/provider-hyperframes-aws-lambda/src/provider.ts
index eeb8ad31..7da9fc0d 100644
--- a/packages/provider-hyperframes-aws-lambda/src/provider.ts
+++ b/packages/provider-hyperframes-aws-lambda/src/provider.ts
@@ -31,7 +31,7 @@ import type {
CanonicalValue,
} from "@hypit/protocol";
import { renderHyperframesCapabilities } from "@hypit/render-hyperframes";
-import { isStreamingArtifactStore } from "@hypit/runtime";
+import { isStreamingResourceStore } from "@hypit/runtime";
import {
createHyperframesAwsLambdaClient,
@@ -163,14 +163,14 @@ async function artifactBytes(
context: EndpointStartContext,
artifact: BlobRef,
): Promise<Uint8Array | AsyncIterable<Uint8Array>> {
- if (isStreamingArtifactStore(context.artifacts)) {
- const chunks = await context.artifacts.open(artifact.digest);
- assert(chunks !== undefined, `HyperFrames Artifact ${artifact.digest} is unavailable`);
+ if (isStreamingResourceStore(context.resources)) {
+ const chunks = await context.resources.open(artifact.resource);
+ assert(chunks !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
return chunks;
}
- const bytes = await context.artifacts.get(artifact.digest);
- assert(bytes !== undefined, `HyperFrames Artifact ${artifact.digest} is unavailable`);
- assert(bytes.byteLength === artifact.size, `HyperFrames Artifact ${artifact.digest} size differs`);
+ const bytes = await context.resources.get(artifact.resource);
+ assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
+ assert(bytes.byteLength === artifact.size, `HyperFrames Artifact ${artifact.resource} size differs`);
return bytes;
}
@@ -179,7 +179,7 @@ function verifySite(site: HyperframesLambdaSite, bucketName: string): void {
assert(site.bucketName === bucketName, "HyperFrames site was deployed to another bucket");
const target = parseS3Uri(site.projectS3Uri);
assert(target.bucket === bucketName && target.key === `sites/${site.siteId}/project.tar.gz`,
- "HyperFrames site URI does not name its content-addressed project");
+ "HyperFrames site URI does not name its deployed project");
positiveInteger(site.bytes, "HyperFrames site bytes");
assert(Number.isFinite(Date.parse(site.uploadedAt)), "HyperFrames site upload timestamp is invalid");
assert(typeof site.uploaded === "boolean", "HyperFrames site upload state is invalid");
@@ -241,8 +241,8 @@ async function storeOutput(
"HyperFrames output exceeded the configured byte limit");
const count = { value: 0 };
const bounded = boundedChunks(source.chunks, maxRenderedBytes, expected, count);
- if (isStreamingArtifactStore(context.artifacts)) {
- return await context.artifacts.putStream(bounded, "video/mp4");
+ if (isStreamingResourceStore(context.resources)) {
+ return await context.resources.putStream(bounded, "video/mp4");
}
const buffers: Uint8Array[] = [];
for await (const chunk of bounded) buffers.push(chunk);
@@ -252,7 +252,7 @@ async function storeOutput(
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
- return await context.artifacts.put(bytes, "video/mp4");
+ return await context.resources.put(bytes, "video/mp4");
}
function fulfillment(
diff --git a/packages/provider-hyperframes-aws-lambda/test/live-canary.ts b/packages/provider-hyperframes-aws-lambda/test/live-canary.ts
index 5276d788..30675df0 100644
--- a/packages/provider-hyperframes-aws-lambda/test/live-canary.ts
+++ b/packages/provider-hyperframes-aws-lambda/test/live-canary.ts
@@ -19,7 +19,7 @@ import {
} from "@hypit/composition";
import {
EndpointRegistry,
- MemoryArtifactStore,
+ MemoryResourceStore,
} from "@hypit/driver-node";
import type {
EndpointOutcome,
@@ -153,13 +153,13 @@ async function main(): Promise<void> {
const document = documentFixture(canaryId);
const need = requestNeed(document, canaryId);
const endpoint = await endpointFor(need);
- const artifacts = new MemoryArtifactStore();
+ const resources = new MemoryResourceStore();
const commandId = `command:hyperframes-aws-canary:${canaryId}`;
const operation = `operation:hyperframes-aws-canary:${canaryId}`;
const context = {
command: { kind: "fulfill-need", id: commandId, need } as const,
need,
- artifacts,
+ resources,
credentials: {},
operation,
};
@@ -181,7 +181,7 @@ async function main(): Promise<void> {
assert.equal(outcome.result.value.kind, "inline");
const visual = outcome.result.value.value as unknown as RenderedVisual;
verifyRenderedVisual(visual);
- const bytes = await artifacts.get(visual.artifact.digest);
+ const bytes = await resources.get(visual.artifact.resource);
assert(bytes !== undefined && bytes.byteLength === visual.artifact.size);
const output = join(work, "visual.mp4");
diff --git a/packages/provider-hyperframes-aws-lambda/test/provider.test.ts b/packages/provider-hyperframes-aws-lambda/test/provider.test.ts
index c68b3d21..e4235dff 100644
--- a/packages/provider-hyperframes-aws-lambda/test/provider.test.ts
+++ b/packages/provider-hyperframes-aws-lambda/test/provider.test.ts
@@ -1,10 +1,10 @@
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { validateDistributedRenderConfig } from "@hyperframes/aws-lambda/sdk";
-import { EndpointRegistry, MemoryArtifactStore } from "@hypit/driver-node";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
import type { EndpointRegistration } from "@hypit/driver-node";
import type { AsyncEndpoint } from "@hypit/endpoint-kit";
import type { HyperframesDocument } from "@hypit/hyperframes";
@@ -28,7 +28,7 @@ import {
hyperframesVisualRequest,
renderHyperframesCapabilities,
} from "@hypit/render-hyperframes";
-import type { ArtifactStore, StreamingArtifactStore } from "@hypit/runtime";
+import type { ResourceStore, StreamingResourceStore } from "@hypit/runtime";
import { hypitPackage as awsLambdaActivation } from "../src/activation.js";
@@ -199,11 +199,11 @@ async function endpointFor(
return { endpoint: resolution.registration.endpoint, registration: resolution.registration };
}
-function context(request: Need, artifacts: ArtifactStore) {
+function context(request: Need, resources: ResourceStore) {
return {
command: { kind: "fulfill-need", id: "command:hyperframes-lambda-test", need: request } as const,
need: request,
- artifacts,
+ resources,
credentials: {},
operation: operation(request),
};
@@ -221,7 +221,7 @@ test("the Lambda Endpoint declines frame domains and requirements it cannot pres
})), false, "an unsupported hardware requirement must fall through to another Endpoint");
const artifact = {
kind: "blob" as const,
- digest: fixtureDigest("lambda-surface-without-verifier"),
+ resource: fixtureResource("lambda-surface-without-verifier"),
size: 100,
mediaType: "image/png",
};
@@ -236,7 +236,7 @@ test("the Lambda Endpoint declines frame domains and requirements it cannot pres
alphaMode: "straight",
timing: { kind: "still" },
}],
- html: `<!doctype html><img data-hypit-surface-artifact="${artifact.digest}" src="hypit-artifact://sha256/${artifact.digest.slice("sha256:".length)}"/>`,
+ html: `<!doctype html><img data-hypit-surface-resource="${artifact.resource}" src="hypit-resource://${artifact.resource}"/>`,
};
assert.equal(supportsAwsLambdaHyperframes(hyperframesVisualRequest(withSurface)), false,
"a deployment without a Surface verifier must fail closed");
@@ -258,19 +258,20 @@ test("the Runtime adapter refuses a hardware-GPU deployment wish instead of igno
}), /does not accept browserGpu/u);
});
-test("one submission is polled and streams the output into the ArtifactStore", async () => {
+test("one submission is polled and streams the output into the ResourceStore", async () => {
const request = requestNeed();
const { client, state } = fakeClient();
const { endpoint, registration } = await endpointFor(request, client);
assert.equal(registration.scheduling?.resources.find((item) =>
item.id.startsWith("pool:"))?.maxActive, 2);
- const memory = new MemoryArtifactStore();
+ const memory = new MemoryResourceStore();
let streamed = 0;
- const artifacts: StreamingArtifactStore = {
+ const resources: StreamingResourceStore = {
put: (bytes, mediaType) => memory.put(bytes, mediaType),
- get: (digest) => memory.get(digest),
- has: (digest) => memory.has(digest),
+ write: (resource, bytes) => memory.write(resource, bytes),
+ get: (resource) => memory.get(resource),
+ has: (resource) => memory.has(resource),
async putStream(chunks, mediaType) {
const values: number[] = [];
for await (const chunk of chunks) {
@@ -279,13 +280,18 @@ test("one submission is polled and streams the output into the ArtifactStore", a
}
return await memory.put(Uint8Array.from(values), mediaType);
},
- async open(digest) {
- const bytes = await memory.get(digest);
+ async writeStream(resource, chunks) {
+ const values: number[] = [];
+ for await (const chunk of chunks) values.push(...chunk);
+ await memory.write(resource, Uint8Array.from(values));
+ },
+ async open(resource) {
+ const bytes = await memory.get(resource);
if (bytes === undefined) return undefined;
return (async function* () { yield bytes; })();
},
};
- const common = context(request, artifacts);
+ const common = context(request, resources);
const started = await endpoint.start(common);
assert.equal(started.status, "pending");
if (started.status !== "pending") return;
@@ -304,14 +310,14 @@ test("one submission is polled and streams the output into the ArtifactStore", a
handle: started.handle,
});
assert.equal(completed.status, "completed", JSON.stringify(completed));
- assert.equal(streamed, 2, "the remote object should use the streaming ArtifactStore facet");
+ assert.equal(streamed, 2, "the remote object should use the streaming ResourceStore facet");
assert.equal(state.opened.length, 1);
if (completed.status !== "completed" || completed.result.value.kind !== "inline") return;
verifyRenderedVisual(completed.result.value.value);
const visual = completed.result.value.value as unknown as RenderedVisual;
assert.equal(visual.frameCount, 60);
- assert.equal(await artifacts.has(visual.artifact.digest), true);
- assert.deepEqual(await artifacts.get(visual.artifact.digest), new Uint8Array([1, 2, 3, 4, 5]));
+ assert.equal(await resources.has(visual.artifact.resource), true);
+ assert.deepEqual(await resources.get(visual.artifact.resource), new Uint8Array([1, 2, 3, 4, 5]));
});
test("running render progress is projected without exposing the private handle", async () => {
@@ -329,7 +335,7 @@ test("running render progress is projected without exposing the private handle",
},
});
const { endpoint } = await endpointFor(request, client);
- const common = context(request, new MemoryArtifactStore());
+ const common = context(request, new MemoryResourceStore());
const started = await endpoint.start(common);
if (started.status !== "pending") return;
const running = await endpoint.poll({
@@ -348,7 +354,7 @@ test("cancellation stops the submitted execution", async () => {
const { client, state } = fakeClient();
const { endpoint } = await endpointFor(request, client);
assert.ok(endpoint.cancel);
- const common = context(request, new MemoryArtifactStore());
+ const common = context(request, new MemoryResourceStore());
const started = await endpoint.start(common);
assert.equal(started.status, "pending");
if (started.status !== "pending") return;
diff --git a/packages/provider-hyperframes-local/README.md b/packages/provider-hyperframes-local/README.md
index b4b4090f..7a8be2ad 100644
--- a/packages/provider-hyperframes-local/README.md
+++ b/packages/provider-hyperframes-local/README.md
@@ -1,7 +1,7 @@
# @hypit/provider-hyperframes-local
Trusted local Provider for the `@hypit/render-hyperframes#render-visual` capability. It stages the
-content-addressed dependencies declared by a `HyperframesDocument`, renders a silent MP4 with the
+Resource dependencies declared by a `HyperframesDocument`, renders a silent MP4 with the
HyperFrames CLI, probes the bytes, and returns a verified `RenderedVisual`. Before staging a typed
Surface it decodes the exact bytes and checks declared dimensions, still/frame timing, SDR/sRGB and
opaque/straight-alpha facts. Artifact size and SHA-256 are checked for every dependency. These are
diff --git a/packages/provider-hyperframes-local/src/provider.ts b/packages/provider-hyperframes-local/src/provider.ts
index 8679cefb..15a0994b 100644
--- a/packages/provider-hyperframes-local/src/provider.ts
+++ b/packages/provider-hyperframes-local/src/provider.ts
@@ -13,7 +13,7 @@ import { stageHyperframesProject } from "@hypit/hyperframes/project";
import { renderHyperframesCapabilities } from "@hypit/render-hyperframes";
import { canonicalize } from "@hypit/protocol";
import { resolveNodePackageExecutable } from "@hypit/package-loader-node";
-import { isStreamingArtifactStore } from "@hypit/runtime";
+import { isStreamingResourceStore } from "@hypit/runtime";
import type { BlobRef, CanonicalValue } from "@hypit/protocol";
import { defineEndpointPackage } from "@hypit/endpoint-kit";
@@ -143,14 +143,14 @@ async function artifactBytes(
context: EndpointInvocationContext,
artifact: BlobRef,
): Promise<Uint8Array | AsyncIterable<Uint8Array>> {
- if (isStreamingArtifactStore(context.artifacts)) {
- const chunks = await context.artifacts.open(artifact.digest);
- assert(chunks !== undefined, `HyperFrames Artifact ${artifact.digest} is unavailable`);
+ if (isStreamingResourceStore(context.resources)) {
+ const chunks = await context.resources.open(artifact.resource);
+ assert(chunks !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
return chunks;
}
- const bytes = await context.artifacts.get(artifact.digest);
- assert(bytes !== undefined, `HyperFrames Artifact ${artifact.digest} is unavailable`);
- assert(bytes.byteLength === artifact.size, `HyperFrames Artifact ${artifact.digest} size differs`);
+ const bytes = await context.resources.get(artifact.resource);
+ assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
+ assert(bytes.byteLength === artifact.size, `HyperFrames Artifact ${artifact.resource} size differs`);
return bytes;
}
@@ -316,9 +316,9 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
timeoutMs: processTimeoutMs,
maxOutputBytes: maxProcessOutputBytes,
});
- const artifact = isStreamingArtifactStore(context.artifacts)
- ? await context.artifacts.putStream(createReadStream(output), "video/mp4")
- : await context.artifacts.put(await readFile(output), "video/mp4");
+ const artifact = isStreamingResourceStore(context.resources)
+ ? await context.resources.putStream(createReadStream(output), "video/mp4")
+ : await context.resources.put(await readFile(output), "video/mp4");
const value: RenderedVisual = sealRenderedVisual({
frameRate: document.frameRate,
frameCount: document.frameCount,
diff --git a/packages/provider-hyperframes-local/test/provider.test.ts b/packages/provider-hyperframes-local/test/provider.test.ts
index 1b977c21..059ad4cf 100644
--- a/packages/provider-hyperframes-local/test/provider.test.ts
+++ b/packages/provider-hyperframes-local/test/provider.test.ts
@@ -5,7 +5,7 @@ import type { CompositableSurfaceRef, RenderedVisual } from "@hypit/media";
import { sealProgramSpace } from "@hypit/program-space";
import { sealComposition, sealVisualTrack } from "@hypit/composition";
import assert from "node:assert/strict";
-import { MemoryArtifactStore, EndpointRegistry } from "@hypit/driver-node";
+import { MemoryResourceStore, EndpointRegistry } from "@hypit/driver-node";
import type { EndpointRegistration } from "@hypit/driver-node";
import type { ImmediateEndpointHandler } from "@hypit/endpoint-kit";
import { compileHyperframesDocument } from "@hypit/hyperframes";
@@ -119,12 +119,12 @@ test("the selected HyperFrames Provider owns one idempotent browser installation
test("local HyperFrames Provider really renders a silent frame-exact MP4 with parallel workers", {
skip: !liveEnabled || !hasFfprobe,
}, async () => {
- const artifacts = new MemoryArtifactStore();
+ const resources = new MemoryResourceStore();
const png = Buffer.from(
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
"base64",
);
- const surfaceArtifact = await artifacts.put(png, "image/png");
+ const surfaceArtifact = await resources.put(png, "image/png");
const surface: CompositableSurfaceRef = {
artifact: surfaceArtifact,
width: 1,
@@ -138,7 +138,7 @@ test("local HyperFrames Provider really renders a silent frame-exact MP4 with pa
const output = await handler({
command: { kind: "fulfill-need", id: "command:local-hyperframes-fixture", need: request },
need: request,
- artifacts,
+ resources,
credentials: {},
});
assert.equal(output.value.kind, "inline");
@@ -147,5 +147,5 @@ test("local HyperFrames Provider really renders a silent frame-exact MP4 with pa
const visual = value as unknown as RenderedVisual;
assert.equal(visual.frameCount, 12);
assert.deepEqual(visual.canvas, { width: 160, height: 96 });
- assert.equal(await artifacts.has(visual.artifact.digest), true);
+ assert.equal(await resources.has(visual.artifact.resource), true);
});
diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.md
index b5633f92..8d1e9013 100644
--- a/packages/provider-hypihub/README.md
+++ b/packages/provider-hypihub/README.md
@@ -38,7 +38,7 @@ an existing `/v1`/`/v1beta` base is accepted) only when choosing HypiHub. The Ru
accepts the origin or either versioned base and normalizes it to `/v1`; missing or insufficient user
credentials should be resolved at [hypit.ai](https://hypit.ai). Referenced image, audio and video
Artifacts are uploaded automatically through `POST /v1/files`, then their returned HTTPS capability
-URLs are used in image and video requests. Uploads are deduplicated by Artifact digest within one
+URLs are used in image and video requests. One referenced Resource is uploaded once within one
Runtime operation. Embedded callers may override that transport with `publicAssetUrl`.
HypiHub exposes MiMo VoiceDesign by default. Set `audio: false` only when the user explicitly selects
diff --git a/packages/provider-hypihub/src/provider.ts b/packages/provider-hypihub/src/provider.ts
index 34911277..b275283c 100644
--- a/packages/provider-hypihub/src/provider.ts
+++ b/packages/provider-hypihub/src/provider.ts
@@ -5,7 +5,7 @@ import type { GeminiRequest } from "@hypit/gemini";
import { canonicalize } from "@hypit/protocol";
import type { BlobRef, CapabilityRef } from "@hypit/protocol";
import { credentialRef } from "@hypit/runtime";
-import type { CredentialRef, ArtifactStore } from "@hypit/runtime";
+import type { CredentialRef, ResourceStore } from "@hypit/runtime";
import { sealText } from "@hypit/text";
import { textTypes } from "@hypit/text";
import { createHypiHubGeminiGenerator } from "./gemini.js";
@@ -25,7 +25,7 @@ export type CreateHypiHubProviderOptions = {
readonly audio?: boolean;
readonly fetch?: typeof globalThis.fetch;
/** Overrides the default POST /v1/files upload for referenced artifacts. */
- readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ArtifactStore) => Promise<string>;
+ readonly publicAssetUrl?: (artifact: BlobRef, artifacts: ResourceStore) => Promise<string>;
};
type Handle = { readonly contract: "hypit.hypihub-operation@1"; readonly jobId: string; readonly route: string; readonly startedAt: number };
@@ -80,9 +80,9 @@ function dataUrl(bytes: Uint8Array, mediaType: string): string {
return `data:${mediaType};base64,${Buffer.from(bytes).toString("base64")}`;
}
-async function resolveArtifactInline(artifacts: ArtifactStore, artifact: BlobRef): Promise<string> {
- const bytes = await artifacts.get(artifact.digest);
- assert(bytes !== undefined, `HypiHub reference artifact ${artifact.digest} is unavailable`);
+async function resolveArtifactInline(artifacts: ResourceStore, artifact: BlobRef): Promise<string> {
+ const bytes = await artifacts.get(artifact.resource);
+ assert(bytes !== undefined, `HypiHub reference artifact ${artifact.resource} is unavailable`);
return dataUrl(bytes, artifact.mediaType);
}
@@ -126,15 +126,15 @@ class HypiHubClient {
}
throw lastError instanceof Error ? lastError : new Error(String(lastError));
}
- async upload(artifact: BlobRef, artifacts: ArtifactStore, apiKey: string): Promise<string> {
- const bytes = await artifacts.get(artifact.digest);
- assert(bytes !== undefined, `HypiHub reference artifact ${artifact.digest} is unavailable`);
- assert(bytes.byteLength === artifact.size, `HypiHub reference artifact ${artifact.digest} size differs`);
+ async upload(artifact: BlobRef, resources: ResourceStore, apiKey: string): Promise<string> {
+ const bytes = await resources.get(artifact.resource);
+ assert(bytes !== undefined, `HypiHub reference artifact ${artifact.resource} is unavailable`);
+ assert(bytes.byteLength === artifact.size, `HypiHub reference artifact ${artifact.resource} size differs`);
const form = new FormData();
const copy = new ArrayBuffer(bytes.byteLength);
new Uint8Array(copy).set(bytes);
form.append("file", new Blob([copy], { type: artifact.mediaType }),
- `${artifact.digest.slice("sha256:".length)}.${mediaExtension(artifact.mediaType)}`);
+ `${artifact.resource}.${mediaExtension(artifact.mediaType)}`);
form.append("purpose", "reference");
const response = await this.json("/files", apiKey, { method: "POST", body: form });
assert(typeof response.url === "string" && /^https:\/\//iu.test(response.url),
@@ -148,7 +148,7 @@ class HypiHubClient {
}
}
-async function complete(client: HypiHubClient, apiKey: string, route: (typeof hypiHubRoutes)[number], id: string, artifacts: ArtifactStore): Promise<EndpointOutcome> {
+async function complete(client: HypiHubClient, apiKey: string, route: (typeof hypiHubRoutes)[number], id: string, artifacts: ResourceStore): Promise<EndpointOutcome> {
const response = await client.json(`/jobs/${encodeURIComponent(id)}/assets`, apiKey); const items = response.items;
assert(Array.isArray(items) && items.length > 0, "HypiHub job has no assets"); const blobs: BlobRef[] = [];
for (const item of items) { const asset = object(item, "HypiHub asset"); assert(typeof asset.url === "string", "HypiHub asset has no URL"); const downloaded = await client.download(asset.url); blobs.push(await artifacts.put(downloaded.bytes, downloaded.mediaType)); }
@@ -159,11 +159,11 @@ async function synthesizeAudio(client: HypiHubClient, context: EndpointInvocatio
const route = hypiHubRouteForCapability(context.need.capability);
assert(route !== undefined && route.media === "audio", "HypiHub does not implement this exact capability");
const compiled = await route.compile(context.need.constraints, async (artifact) => publicAssetUrl === undefined
- ? await resolveArtifactInline(context.artifacts, artifact)
- : await publicAssetUrl(artifact, context.artifacts));
+ ? await resolveArtifactInline(context.resources, artifact)
+ : await publicAssetUrl(artifact, context.resources));
await verifyModelRoute(client, credential(context), compiled.model, "audio_speech");
const audio = await client.binary("/audio/speech", credential(context), { model: compiled.model, ...(compiled.input as Record<string, unknown>) });
- const artifact = await context.artifacts.put(audio.bytes, audio.mediaType);
+ const artifact = await context.resources.put(audio.bytes, audio.mediaType);
return { value: route.packageResult([artifact]) };
}
@@ -175,12 +175,12 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
assert(route !== undefined, "HypiHub does not implement this exact capability"); const apiKey = credential(context);
const uploaded = new Map<string, Promise<string>>();
const resolve = (artifact: BlobRef): Promise<string> => {
- const existing = uploaded.get(artifact.digest);
+ const existing = uploaded.get(artifact.resource);
if (existing !== undefined) return existing;
const promise = publicAssetUrl === undefined
- ? client.upload(artifact, context.artifacts, apiKey)
- : publicAssetUrl(artifact, context.artifacts);
- uploaded.set(artifact.digest, promise);
+ ? client.upload(artifact, context.resources, apiKey)
+ : publicAssetUrl(artifact, context.resources);
+ uploaded.set(artifact.resource, promise);
return promise;
};
const compiled = await route.compile(context.need.constraints, resolve);
@@ -196,7 +196,7 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
await verifyModelRoute(client, apiKey, compiled.model,
path === "/images/edits" ? "image_edits" : path === "/images/generations" ? "images" : "videos");
const response = await client.json(path, apiKey, { method: "POST", headers: { "content-type": "application/json", "idempotency-key": context.operation }, body: JSON.stringify({ model: compiled.model, ...input }) });
- const status = response.status; if (status === "succeeded" || status === "completed") return await complete(client, apiKey, route, jobId(response), context.artifacts);
+ const status = response.status; if (status === "succeeded" || status === "completed") return await complete(client, apiKey, route, jobId(response), context.resources);
const handle: Handle = { contract: "hypit.hypihub-operation@1", jobId: jobId(response), route: capabilityKey(route.capability), startedAt: Date.now() };
return wakeAfter(canonicalize(handle), pollIntervalMs, Date.now(), { phase: "submitted" });
} catch (error) { return failure(error); }
@@ -214,7 +214,7 @@ function endpoint(client: HypiHubClient, pollIntervalMs: number, maxOperationMs:
throw new Error(`HypiHub job ${status}${typeof detail === "string" ? `: ${detail}` : ""}`);
}
if (status !== "succeeded" && status !== "completed") throw new Error(`HypiHub returned unknown job status ${String(status)}`);
- return await complete(client, credential(context), route, handle.jobId, context.artifacts);
+ return await complete(client, credential(context), route, handle.jobId, context.resources);
} catch (error) { return failure(error); }
},
};
@@ -243,8 +243,8 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}
});
const parts: Array<{ text: string } | { inlineData: { mimeType: string; data: string } }> = [{ text: request.prompt }];
for (const item of request.media) {
- const bytes = await context.artifacts.get(item.artifact.digest);
- assert(bytes !== undefined, `HypiHub Gemini reference artifact ${item.artifact.digest} is unavailable`);
+ const bytes = await context.resources.get(item.artifact.resource);
+ assert(bytes !== undefined, `HypiHub Gemini reference artifact ${item.artifact.resource} is unavailable`);
parts.push({ inlineData: { mimeType: item.artifact.mediaType, data: Buffer.from(bytes).toString("base64") } });
}
const value = await generate({ parts, instruction: request.instruction });
diff --git a/packages/provider-hypihub/test/provider.test.ts b/packages/provider-hypihub/test/provider.test.ts
index e640c986..4df01367 100644
--- a/packages/provider-hypihub/test/provider.test.ts
+++ b/packages/provider-hypihub/test/provider.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { EndpointRegistry, MemoryArtifactStore } from "@hypit/driver-node";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
import type { AsyncEndpoint } from "@hypit/endpoint-kit";
import { geminiCapabilities, sealGeminiRequest } from "@hypit/gemini";
import type { CanonicalValue, Need } from "@hypit/protocol";
@@ -53,8 +53,8 @@ test("HypiHub exposes VoiceDesign by default and permits an explicit alternate a
});
test("HypiHub uploads referenced Artifacts once, submits their HTTPS URLs, and persists the result", async () => {
- const artifacts = new MemoryArtifactStore();
- const reference = await artifacts.put(new Uint8Array([1, 2, 3]), "image/png");
+ const resources = new MemoryResourceStore();
+ const reference = await resources.put(new Uint8Array([1, 2, 3]), "image/png");
const request = need(sealSeedanceRequest("seedance-2-mini", {
prompt: ["A presenter turns toward camera."],
referenceImage: [
@@ -105,7 +105,7 @@ test("HypiHub uploads referenced Artifacts once, submits their HTTPS URLs, and p
const endpoint = await endpointFor(request, fakeFetch);
const common = {
command: { kind: "fulfill-need", id: "command:hypihub-test", need: request } as const,
- need: request, artifacts, credentials: { apiKey: { secret: "test-key" } },
+ need: request, resources, credentials: { apiKey: { secret: "test-key" } },
operation: "operation:hypihub-test",
};
const started = await endpoint.start(common);
@@ -118,9 +118,9 @@ test("HypiHub uploads referenced Artifacts once, submits their HTTPS URLs, and p
});
test("HypiHub fulfills Gemini through the Runtime endpoint and uploads every media Artifact", async () => {
- const artifacts = new MemoryArtifactStore();
- const image = await artifacts.put(new Uint8Array([1, 2, 3]), "image/png");
- const video = await artifacts.put(new Uint8Array([4, 5, 6]), "video/mp4");
+ const resources = new MemoryResourceStore();
+ const image = await resources.put(new Uint8Array([1, 2, 3]), "image/png");
+ const video = await resources.put(new Uint8Array([4, 5, 6]), "video/mp4");
const request: Need = {
id: "need:hypihub-gemini",
capability: geminiCapabilities["gemini-3.7-flash"],
@@ -154,7 +154,7 @@ test("HypiHub fulfills Gemini through the Runtime endpoint and uploads every med
assert.equal(resolution.registration.kind, "immediate");
const result = await resolution.registration.handler({
command: { kind: "fulfill-need", id: "command:hypihub-gemini", need: request },
- need: request, artifacts, credentials: { apiKey: { secret: "test-key" } },
+ need: request, resources, credentials: { apiKey: { secret: "test-key" } },
});
assert.deepEqual(result.value, { kind: "inline", value: { value: "provider works" } });
assert.deepEqual(uploads, ["image/png", "video/mp4"]);
diff --git a/packages/provider-hypihub/test/routes.test.ts b/packages/provider-hypihub/test/routes.test.ts
index fcc4a920..740df5a8 100644
--- a/packages/provider-hypihub/test/routes.test.ts
+++ b/packages/provider-hypihub/test/routes.test.ts
@@ -5,7 +5,7 @@ import { hypiHubRoutes } from "../src/routes.js";
const image = {
kind: "blob" as const,
- digest: `sha256:${"1".repeat(64)}`,
+ resource: "res_hypihub-route-1",
size: 3,
mediaType: "image/png",
};
@@ -81,7 +81,7 @@ test("HypiHub Seedance sends reference images through the public top-level field
webSearch: [false],
referenceImage: [
{ role: "image", artifact: image },
- { role: "image", artifact: { ...image, digest: `sha256:${"2".repeat(64)}` } },
+ { role: "image", artifact: { ...image, resource: "res_hypihub-route-2" } },
],
},
}, resolve);
@@ -116,7 +116,7 @@ test("HypiHub uses ref_video_url for one video and the public array for multiple
const route = hypiHubRoutes.find((item) => item.capability.name === "minimax-h3");
assert.ok(route);
const video = { ...image, mediaType: "video/mp4" };
- const resolveVideo = async (artifact: typeof video) => `https://hypit.ai/files/${artifact.digest.slice(-1)}.mp4`;
+ const resolveVideo = async (artifact: typeof video) => `https://hypit.ai/files/${artifact.resource.slice(-1)}.mp4`;
const single = await route.compile({ ports: {
prompt: ["animate"], duration: [6],
@@ -131,7 +131,7 @@ test("HypiHub uses ref_video_url for one video and the public array for multiple
prompt: ["animate"], duration: [6],
referenceVideo: [
{ role: "video", artifact: video },
- { role: "video", artifact: { ...video, digest: `sha256:${"2".repeat(64)}` } },
+ { role: "video", artifact: { ...video, resource: "res_hypihub-route-2" } },
],
} }, resolveVideo);
assert.deepEqual(multiple.input, {
diff --git a/packages/provider-image-opencv-local/README.md b/packages/provider-image-opencv-local/README.md
index 915cff59..d7d85330 100644
--- a/packages/provider-image-opencv-local/README.md
+++ b/packages/provider-image-opencv-local/README.md
@@ -3,7 +3,7 @@
Local OpenCV/NumPy realization of the single `@hypit/raster` capability.
Image Transform and Image Compose lower their different author meanings to one closed RasterRequest.
-One Handler stages its content-addressed inputs, and one Python interpreter shares decoding, fit,
+One Handler stages its declared Resource inputs, and one Python interpreter shares decoding, fit,
interpolation, alpha and encoding primitives across both variants. It runs in a bounded child process
and stores one new image Artifact. Temporary paths, OpenCV details and diagnostics stay inside the
Endpoint and never enter the image Product.
diff --git a/packages/provider-image-opencv-local/src/provider.ts b/packages/provider-image-opencv-local/src/provider.ts
index e3e1a306..a59c573a 100644
--- a/packages/provider-image-opencv-local/src/provider.ts
+++ b/packages/provider-image-opencv-local/src/provider.ts
@@ -105,26 +105,26 @@ export function createLocalOpenCvImageProvider(config: CreateLocalOpenCvImagePro
returns: artifactTypes.blob,
handler: async (context): Promise<EndpointFulfillment> => {
const need = request(context.need.constraints);
- const sources = [...new Map(rasterSources(need).map((source) => [source.digest, source])).values()];
+ const sources = [...new Map(rasterSources(need).map((source) => [source.resource, source])).values()];
const totalInputBytes = sources.reduce((sum, source) => sum + source.size, 0);
assert(totalInputBytes <= maxInputBytes, "Raster inputs exceed their configured byte limit");
const work = await mkdtemp(join(tmpdir(), "hypit-raster-opencv-"));
try {
const paths = new Map<string, string>();
for (const [index, source] of sources.entries()) {
- const bytes = await context.artifacts.get(source.digest);
- assert(bytes !== undefined, `Raster source Artifact ${source.digest} is unavailable`);
+ const bytes = await context.resources.get(source.resource);
+ assert(bytes !== undefined, `Raster source Artifact ${source.resource} is unavailable`);
assert(bytes.byteLength === source.size, "Raster source size differs from its BlobRef");
const path = join(work, `source-${String(index + 1).padStart(4, "0")}.bin`);
await writeFile(path, bytes);
- paths.set(source.digest, path);
+ paths.set(source.resource, path);
}
const runtimeRequest = need.kind === "transform"
- ? { kind: "transform", source: paths.get(need.source.digest), operations: need.operations }
+ ? { kind: "transform", source: paths.get(need.source.resource), operations: need.operations }
: {
kind: "compose", canvas: need.canvas, background: need.background,
layers: need.layers.map((layer) => ({
- source: paths.get(layer.source.digest), frame: layer.frame, fit: layer.fit,
+ source: paths.get(layer.source.resource), frame: layer.frame, fit: layer.fit,
interpolation: layer.interpolation, opacity: layer.opacity,
})),
};
@@ -141,7 +141,7 @@ export function createLocalOpenCvImageProvider(config: CreateLocalOpenCvImagePro
assert(info.isFile() && info.size > 0 && info.size <= maxOutputBytes,
"OpenCV raster execution produced an invalid output size");
const mediaType = rasterOutputMediaType(need);
- const artifact = await context.artifacts.put(await readFile(output), mediaType);
+ const artifact = await context.resources.put(await readFile(output), mediaType);
return {
value: artifact,
};
diff --git a/packages/provider-image-opencv-local/test/provider.test.ts b/packages/provider-image-opencv-local/test/provider.test.ts
index dabcccf2..eec0ead5 100644
--- a/packages/provider-image-opencv-local/test/provider.test.ts
+++ b/packages/provider-image-opencv-local/test/provider.test.ts
@@ -4,7 +4,7 @@ import { join, resolve } from "node:path";
import test from "node:test";
import { artifactTypes } from "@hypit/artifact";
-import { EndpointRegistry, MemoryArtifactStore } from "@hypit/driver-node";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
import {
gptImageDenoiseV1,
sealImageTransformProgram,
@@ -98,12 +98,12 @@ const hasOpenCv = spawnSync(openCvPython, ["-c", "import cv2, numpy"], { stdio:
test("the local Provider returns only a new image BlobArtifact", {
skip: !liveEnabled || !hasOpenCv,
}, async () => {
- const artifacts = new MemoryArtifactStore();
+ const resources = new MemoryResourceStore();
const png = Buffer.from(
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
"base64",
);
- const source = await artifacts.put(png, "image/png");
+ const source = await resources.put(png, "image/png");
const program = sealImageTransformProgram({
operations: [{
kind: "resize",
@@ -122,14 +122,14 @@ test("the local Provider returns only a new image BlobArtifact", {
const result = await resolution.registration.handler({
command: { kind: "fulfill-need", id: "command:image-transform", need: request },
need: request,
- artifacts,
+ resources,
credentials: {},
});
assert.equal(result.value.kind, "blob");
assert.equal(result.value.mediaType, "image/png");
- assert.equal(await artifacts.has(result.value.digest), true);
+ assert.equal(await resources.has(result.value.resource), true);
assert.deepEqual(Object.keys(result.value).sort(), ["digest", "kind", "mediaType", "size"]);
- const output = await artifacts.get(result.value.digest);
+ const output = await resources.get(result.value.resource);
assert(output !== undefined);
const encoded = Buffer.from(output);
assert.equal(encoded.readUInt32BE(16), 64);
@@ -139,12 +139,12 @@ test("the local Provider returns only a new image BlobArtifact", {
test("the local Provider composes ordered Layers into exact Canvas pixels", {
skip: !liveEnabled || !hasOpenCv,
}, async () => {
- const artifacts = new MemoryArtifactStore();
+ const resources = new MemoryResourceStore();
const png = Buffer.from(
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
"base64",
);
- const source = await artifacts.put(png, "image/png");
+ const source = await resources.put(png, "image/png");
const request = composeNeed(source);
const registry = new EndpointRegistry();
await createLocalOpenCvImageProvider({ pythonExecutable: openCvPython }).install(registry);
@@ -153,11 +153,11 @@ test("the local Provider composes ordered Layers into exact Canvas pixels", {
assert.equal(resolution.registration.kind, "immediate");
const result = await resolution.registration.handler({
command: { kind: "fulfill-need", id: "command:image-compose", need: request },
- need: request, artifacts, credentials: {},
+ need: request, resources, credentials: {},
});
assert.equal(result.value.kind, "blob");
if (result.value.kind !== "blob") return;
- const output = await artifacts.get(result.value.digest);
+ const output = await resources.get(result.value.resource);
assert(output !== undefined);
const probe = spawnSync(openCvPython, ["-c", [
"import cv2, numpy as np, sys",
diff --git a/packages/provider-kie/package.json b/packages/provider-kie/package.json
index cf26f665..9f4f384a 100644
--- a/packages/provider-kie/package.json
+++ b/packages/provider-kie/package.json
@@ -20,7 +20,7 @@
"@hypit/runtime-kit": "workspace:*"
},
"devDependencies": {
- "@hypit/artifact-store-fs": "workspace:*",
+ "@hypit/resource-store-fs": "workspace:*",
"@hypit/component-kit": "workspace:*",
"@hypit/core": "workspace:*",
"@hypit/credential-store-env": "workspace:*",
diff --git a/packages/provider-kie/src/provider.ts b/packages/provider-kie/src/provider.ts
index a6f6b663..01c8cfcf 100644
--- a/packages/provider-kie/src/provider.ts
+++ b/packages/provider-kie/src/provider.ts
@@ -10,7 +10,7 @@ import {
import type {
BlobRef,
CanonicalValue,
- Digest,
+ ResourceId,
Need,
} from "@hypit/protocol";
import type { GenerationRequest } from "@hypit/generation";
@@ -18,8 +18,8 @@ import {
defineEndpointPackage,
wakeAfter,
} from "@hypit/endpoint-kit";
-import { credentialRef, isStreamingArtifactStore } from "@hypit/runtime";
-import type { ArtifactStore, CredentialRef } from "@hypit/runtime";
+import { credentialRef, isStreamingResourceStore } from "@hypit/runtime";
+import type { ResourceStore, CredentialRef } from "@hypit/runtime";
import {
kieRouteForCapability,
@@ -214,46 +214,43 @@ class KieClient {
}
}
- async upload(artifact: BlobRef, artifacts: ArtifactStore, apiKey: string): Promise<string> {
+ async upload(artifact: BlobRef, resources: ResourceStore, apiKey: string): Promise<string> {
if (artifact.size > this.#options.maxArtifactBytes) {
- throw new KieError("KIE_ARTIFACT_TOO_LARGE", `Artifact ${artifact.digest} exceeds the configured KIE upload limit`);
+ throw new KieError("KIE_ARTIFACT_TOO_LARGE", `Artifact ${artifact.resource} exceeds the configured KIE upload limit`);
}
- const hex = artifact.digest.slice("sha256:".length);
- const fileName = `${hex}.${mediaExtension(artifact.mediaType)}`;
- const boundary = `hypit-${hex}`;
+ const fileName = `${artifact.resource}.${mediaExtension(artifact.mediaType)}`;
+ const boundary = `hypit-${artifact.resource}`;
const encode = (value: string) => new TextEncoder().encode(value);
const fileHead = encode(
`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${fileName}"\r\n`
+ `Content-Type: ${artifact.mediaType}\r\n\r\n`,
);
const fields = encode(
- `\r\n--${boundary}\r\nContent-Disposition: form-data; name="uploadPath"\r\n\r\nsvml/${hex.slice(0, 2)}`
+ `\r\n--${boundary}\r\nContent-Disposition: form-data; name="uploadPath"\r\n\r\nsvml/resources`
+ `\r\n--${boundary}\r\nContent-Disposition: form-data; name="fileName"\r\n\r\n${fileName}`
+ `\r\n--${boundary}--\r\n`,
);
- const source = isStreamingArtifactStore(artifacts)
- ? await artifacts.open(artifact.digest)
- : await artifacts.get(artifact.digest).then((bytes) => bytes === undefined
+ const source = isStreamingResourceStore(resources)
+ ? await resources.open(artifact.resource)
+ : await resources.get(artifact.resource).then((bytes) => bytes === undefined
? undefined
: (async function* () { yield bytes; })());
if (source === undefined) {
- throw new KieError("KIE_ARTIFACT_MISSING", `Artifact ${artifact.digest} is unavailable`);
+ throw new KieError("KIE_ARTIFACT_MISSING", `Artifact ${artifact.resource} is unavailable`);
}
const maximum = this.#options.maxArtifactBytes;
const multipart = (async function* () {
yield fileHead;
- const hash = createHash("sha256");
let size = 0;
for await (const chunk of source) {
size += chunk.byteLength;
if (size > artifact.size || size > maximum) {
- throw new KieError("KIE_ARTIFACT_SIZE_MISMATCH", `Artifact ${artifact.digest} size differs`);
+ throw new KieError("KIE_ARTIFACT_SIZE_MISMATCH", `Artifact ${artifact.resource} size differs`);
}
- hash.update(chunk);
yield chunk;
}
- if (size !== artifact.size || `sha256:${hash.digest("hex")}` !== artifact.digest) {
- throw new KieError("KIE_ARTIFACT_SIZE_MISMATCH", `Artifact ${artifact.digest} bytes differ`);
+ if (size !== artifact.size) {
+ throw new KieError("KIE_ARTIFACT_SIZE_MISMATCH", `Artifact ${artifact.resource} size differs`);
}
yield fields;
})();
@@ -455,12 +452,12 @@ function endpoint(options: {
const route = kieRouteForCapability(context.need.capability);
if (route === undefined) throw new KieError("KIE_UNSUPPORTED_CAPABILITY", "KIE does not implement this exact capability");
const key = secret(context);
- const uploaded = new Map<Digest, Promise<string>>();
+ const uploaded = new Map<ResourceId, Promise<string>>();
const resolve = (artifact: BlobRef): Promise<string> => {
- const existing = uploaded.get(artifact.digest);
+ const existing = uploaded.get(artifact.resource);
if (existing !== undefined) return existing;
- const promise = options.client.upload(artifact, context.artifacts, key);
- uploaded.set(artifact.digest, promise);
+ const promise = options.client.upload(artifact, context.resources, key);
+ uploaded.set(artifact.resource, promise);
return promise;
};
const task = await route.compile(context.need.constraints, resolve);
@@ -516,8 +513,8 @@ function endpoint(options: {
const artifacts: BlobRef[] = [];
for (const url of urls) {
const downloaded = await options.client.download(url, route.media, key);
- if (isStreamingArtifactStore(context.artifacts)) {
- artifacts.push(await context.artifacts.putStream(downloaded.chunks, downloaded.mediaType));
+ if (isStreamingResourceStore(context.resources)) {
+ artifacts.push(await context.resources.putStream(downloaded.chunks, downloaded.mediaType));
} else {
const chunks: Uint8Array[] = [];
let size = 0;
@@ -531,7 +528,7 @@ function endpoint(options: {
bytes.set(chunk, offset);
offset += chunk.byteLength;
}
- artifacts.push(await context.artifacts.put(bytes, downloaded.mediaType));
+ artifacts.push(await context.resources.put(bytes, downloaded.mediaType));
}
}
const result = route.packageResult(artifacts);
@@ -598,4 +595,3 @@ export function createKieProvider(config: CreateKieProviderOptions) {
})),
});
}
-import { createHash } from "node:crypto";
diff --git a/packages/provider-kie/test/live-smoke.ts b/packages/provider-kie/test/live-smoke.ts
index d2def133..7712ef9f 100644
--- a/packages/provider-kie/test/live-smoke.ts
+++ b/packages/provider-kie/test/live-smoke.ts
@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
-import { FileArtifactStore } from "@hypit/artifact-store-fs";
+import { FileResourceStore } from "@hypit/resource-store-fs";
import { EnvironmentCredentialStore } from "@hypit/credential-store-env";
import { registerTypeValidatorFacets } from "@hypit/component-kit";
import {
@@ -252,7 +252,7 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {
const referencePath = process.env.HYPIT_KIE_SMOKE_REFERENCE;
if (referencePath !== undefined) {
const absolute = resolve(referencePath);
- const store = new FileArtifactStore(join(root, ".svml", "artifacts"));
+ const store = new FileResourceStore(join(root, ".svml", "artifacts"));
const reference = await store.put(await readFile(absolute), referenceMediaType(absolute));
cases.push({
key: "gpt-image-2-edit",
@@ -333,14 +333,13 @@ function generatedArtifact(item: SmokeCase, records: readonly TypedRecord[]): Bl
const artifacts = product[item.media === "image" ? "images" : "videos"];
assert(Array.isArray(artifacts) && artifacts.length > 0, `${item.key} generated Product has no artifacts`);
const first = object(artifacts[0], `${item.key} generated artifact`);
- assert(first.kind === "blob" && typeof first.digest === "string"
+ assert(first.kind === "blob" && typeof first.resource === "string"
&& typeof first.size === "number" && typeof first.mediaType === "string", `${item.key} BlobRef is invalid`);
return first as unknown as BlobRef;
}
async function inspectArtifact(root: string, item: SmokeCase, artifact: BlobRef): Promise<string> {
- const artifactHex = artifact.digest.slice("sha256:".length);
- const artifactPath = join(root, ".svml", "artifacts", "sha256", artifactHex.slice(0, 2), artifactHex);
+ const artifactPath = join(root, ".svml", "artifacts", "resources", artifact.resource);
const inspectPath = join(root, `${item.key}-live${resultExtension(artifact.mediaType)}`);
await writeFile(inspectPath, await readFile(artifactPath), { flag: "w" });
return inspectPath;
@@ -376,7 +375,7 @@ async function main(): Promise<void> {
buildCatalog: state.catalog,
operationStore: state.operations,
dispatchStore: state.dispatch,
- artifactStore: new FileArtifactStore(join(root, ".hypit", "artifacts")),
+ resourceStore: new FileResourceStore(join(root, ".hypit", "artifacts")),
credentialStore: new EnvironmentCredentialStore(),
components: [
generationComponent,
@@ -404,7 +403,7 @@ async function main(): Promise<void> {
if (build.status !== "complete") throw new Error(failureMessage(item, build));
const artifact = generatedArtifact(item, build.state.records);
const inspectPath = await inspectArtifact(root, item, artifact);
- console.log(`[${item.key}] artifact: ${artifact.digest}`);
+ console.log(`[${item.key}] artifact: ${artifact.resource}`);
console.log(`[${item.key}] inspection copy: ${inspectPath}`);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
diff --git a/packages/provider-kie/test/models.test.ts b/packages/provider-kie/test/models.test.ts
index db4747c1..3bd37ac1 100644
--- a/packages/provider-kie/test/models.test.ts
+++ b/packages/provider-kie/test/models.test.ts
@@ -4,7 +4,7 @@ import { videoContractManifests } from "../../../test/support/video-domain.js";
import { createResolvedClosure } from "@hypit/core";
import { verifyGraphFragment } from "@hypit/elaborator";
-import { MemoryArtifactStore } from "@hypit/driver-node";
+import { MemoryResourceStore } from "@hypit/driver-node";
import {
assertMappingCoversPorts,
compileWireRequest,
@@ -56,7 +56,7 @@ function capabilityKey(ref: CapabilityRef): string {
return `${ref.module.name}@${ref.module.version}#${ref.name}`;
}
-const upload = async (artifact: { readonly digest: string }) => `https://upload.test/${artifact.digest}`;
+const upload = async (artifact: { readonly resource: string }) => `https://upload.test/${artifact.resource}`;
test("the selected KIE release is six exact model families and no Grok image capability", () => {
assert.equal(kieModelCatalog.length, 11);
@@ -146,7 +146,7 @@ test("Seedream safety policy remains explicit author content", () => {
});
test("all eleven exact capabilities route to their documented KIE model slug", async () => {
- const store = new MemoryArtifactStore();
+ const store = new MemoryResourceStore();
const image = await store.put(new Uint8Array([1]), "image/png");
const video = await store.put(new Uint8Array([2]), "video/mp4");
const audio = await store.put(new Uint8Array([3]), "audio/wav");
@@ -265,7 +265,7 @@ test("Seedance 2.5 maps its exact request without leaking KIE envelope controls
});
test("one model reaching a service that splits it keeps the reference roles intact", async () => {
- const store = new MemoryArtifactStore();
+ const store = new MemoryResourceStore();
const image = await store.put(new Uint8Array([1]), "image/png");
const audio = await store.put(new Uint8Array([3]), "audio/wav");
const request = sealSeedanceRequest("seedance-2-mini", {
@@ -283,8 +283,8 @@ test("one model reaching a service that splits it keeps the reference roles inta
const task = await compileWireRequest(mapping, request, upload);
assert.deepEqual(task.input, {
prompt: "A presenter speaks.",
- reference_image_urls: [`https://upload.test/${image.digest}`],
- reference_audio_urls: [`https://upload.test/${audio.digest}`],
+ reference_image_urls: [`https://upload.test/${image.resource}`],
+ reference_audio_urls: [`https://upload.test/${audio.resource}`],
resolution: "720p",
aspect_ratio: "9:16",
duration: 5,
diff --git a/packages/provider-kie/test/provider.test.ts b/packages/provider-kie/test/provider.test.ts
index 4b1a3703..5d68f793 100644
--- a/packages/provider-kie/test/provider.test.ts
+++ b/packages/provider-kie/test/provider.test.ts
@@ -1,9 +1,9 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
- MemoryArtifactStore,
+ MemoryResourceStore,
EndpointRegistry,
} from "@hypit/driver-node";
import type { EndpointRegistration } from "@hypit/driver-node";
@@ -69,7 +69,7 @@ test("all KIE capabilities share one asynchronous task engine and differ only by
prompt: ["A clean studio shot."], resolution: ["720p"], aspectRatio: ["16:9"],
duration: [5], generateAudio: [false], webSearch: [false],
}) as unknown as CanonicalValue);
- const source = { kind: "blob" as const, digest: fixtureDigest("lane-source"), size: 1, mediaType: "image/png" };
+ const source = { kind: "blob" as const, resource: fixtureResource("lane-source"), size: 1, mediaType: "image/png" };
const removal = removeBackgroundNeed(backgroundRemovalRequest(source) as unknown as CanonicalValue);
const seedResolution = registry.resolve(seed);
const removalResolution = registry.resolve(removal);
@@ -87,9 +87,9 @@ test("all KIE capabilities share one asynchronous task engine and differ only by
});
});
-test("KIE uploads referenced artifacts, polls one task, and persists generated bytes", async () => {
- const artifacts = new MemoryArtifactStore();
- const firstFrame = await artifacts.put(new Uint8Array([1, 2, 3]), "image/png");
+test("KIE uploads referenced resources, polls one task, and persists generated bytes", async () => {
+ const resources = new MemoryResourceStore();
+ const firstFrame = await resources.put(new Uint8Array([1, 2, 3]), "image/png");
const requestValue = sealSeedanceRequest("seedance-2-mini", {
prompt: ["A presenter turns toward camera."],
firstFrame: [{ role: "image", artifact: firstFrame }],
@@ -110,7 +110,7 @@ test("KIE uploads referenced artifacts, polls one task, and persists generated b
const chunks: Uint8Array[] = [];
for await (const chunk of init?.body as unknown as AsyncIterable<Uint8Array>) chunks.push(chunk);
const multipart = Buffer.concat(chunks).toString("latin1");
- assert.match(multipart, /name="fileName"\r\n\r\n[0-9a-f]{64}\.png/u);
+ assert.match(multipart, /name="fileName"\r\n\r\nres_[a-zA-Z0-9-]+\.png/u);
assert.ok(Buffer.concat(chunks).includes(Buffer.from([1, 2, 3])));
return Response.json({
success: true,
@@ -151,7 +151,7 @@ test("KIE uploads referenced artifacts, polls one task, and persists generated b
const common = {
command: { kind: "fulfill-need", id: "command:kie-test", need: request } as const,
need: request,
- artifacts,
+ resources,
credentials: { apiKey: { secret: "test-key" } },
operation: operation(request),
};
@@ -172,14 +172,14 @@ test("KIE uploads referenced artifacts, polls one task, and persists generated b
const result = completed.result.value.kind === "inline"
? completed.result.value.value as Record<string, unknown> : {};
assert.equal("model" in result, false, "model choice belongs to the request graph");
- const videos = result.videos as Array<{ digest: string }>;
+ const videos = result.videos as Array<{ resource: string }>;
assert.equal(videos.length, 1);
- assert.equal(await artifacts.has(videos[0]!.digest as `sha256:${string}`), true);
+ assert.equal(await resources.has(videos[0]!.resource as `res_${string}`), true);
});
test("KIE fulfills generic Background Removal with the documented Recraft wire contract", async () => {
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(new Uint8Array([1, 2, 3, 4]), "image/png");
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(new Uint8Array([1, 2, 3, 4]), "image/png");
const request = removeBackgroundNeed(backgroundRemovalRequest(source) as unknown as CanonicalValue);
const calls: string[] = [];
const fakeFetch: typeof globalThis.fetch = async (input, init) => {
@@ -210,7 +210,7 @@ test("KIE fulfills generic Background Removal with the documented Recraft wire c
const { endpoint } = await endpointFor(request, fakeFetch);
const common = {
command: { kind: "fulfill-need", id: "command:remove-background", need: request } as const,
- need: request, artifacts, credentials: { apiKey: { secret: "test-key" } }, operation: operation(request),
+ need: request, resources, credentials: { apiKey: { secret: "test-key" } }, operation: operation(request),
};
const started = await endpoint.start(common);
assert.equal(started.status, "pending");
diff --git a/packages/provider-media-aws-lambda/README.md b/packages/provider-media-aws-lambda/README.md
deleted file mode 100644
index 763cce2a..00000000
--- a/packages/provider-media-aws-lambda/README.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# `@hypit/provider-media-aws-lambda`
-
-Retired AWS Lambda Endpoint package for the nine capabilities declared by
-`@hypit/media-pipeline` and implemented by `@hypit/media-execution`.
-
-This route required the Runtime and Lambda function to share one selected S3 Artifact Store. Runtime
-Profiles no longer select an Artifact Store: each Build has private transient working resources and
-publishes its public outputs into the project Build Result. Consequently this package cannot be
-activated from a current Runtime Profile.
-
-The source remains only as the description of the former transport. A replacement must own its
-remote staging internally, import completed resources into the current Build working store, and
-leave no Runtime-wide storage choice behind.
diff --git a/packages/provider-media-aws-lambda/package.json b/packages/provider-media-aws-lambda/package.json
deleted file mode 100644
index ac7f9cc9..00000000
--- a/packages/provider-media-aws-lambda/package.json
+++ /dev/null
@@ -1,26 +0,0 @@
-{
- "name": "@hypit/provider-media-aws-lambda",
- "version": "0.0.0-dev",
- "license": "SEE LICENSE IN LICENSE",
- "private": true,
- "type": "module",
- "exports": {
- ".": "./src/index.ts"
- },
- "hypit": {
- "activation": "./src/activation.ts"
- },
- "dependencies": {
- "@hypit/artifact": "workspace:*",
- "@hypit/endpoint-kit": "workspace:*",
- "@hypit/media": "workspace:*",
- "@hypit/media-pipeline": "workspace:*",
- "@hypit/protocol": "workspace:*",
- "@hypit/runtime-kit": "workspace:*",
- "@hypit/speech": "workspace:*",
- "@hypit/transport-aws-lambda": "workspace:*"
- },
- "devDependencies": {
- "@hypit/driver-node": "workspace:*"
- }
-}
diff --git a/packages/provider-media-aws-lambda/src/activation.ts b/packages/provider-media-aws-lambda/src/activation.ts
deleted file mode 100644
index 5892170e..00000000
--- a/packages/provider-media-aws-lambda/src/activation.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import {
- createRuntimeEndpointAdapterFacet,
-} from "@hypit/runtime-kit";
-
-const awsLambdaMediaRuntimeAdapter = createRuntimeEndpointAdapterFacet({
- use: "@hypit/provider-media-aws-lambda",
- activate(_context) {
- throw new Error(
- "@hypit/provider-media-aws-lambda is retired: it depended on a Runtime-wide shared S3 ArtifactStore."
- + " Use a Provider that owns its remote transport and imports completed resources into the Build working store.",
- );
- },
-});
-
-export const hypitPackage = {
- format: "hypit.node-package@1" as const,
- hostFacets: [awsLambdaMediaRuntimeAdapter],
-};
-
-export default hypitPackage;
diff --git a/packages/provider-media-aws-lambda/src/contract.ts b/packages/provider-media-aws-lambda/src/contract.ts
deleted file mode 100644
index bbf89425..00000000
--- a/packages/provider-media-aws-lambda/src/contract.ts
+++ /dev/null
@@ -1,154 +0,0 @@
-import { canonicalize } from "@hypit/protocol";
-import type { CanonicalValue, StoredValue } from "@hypit/protocol";
-
-/**
- * The envelope between the Endpoint and the function it invokes.
- *
- * Both sides parse it. The Endpoint parses because a function is a deployed
- * artifact that may be older than the caller; the function parses because an
- * invocation is an untrusted input even when the account is trusted. Neither
- * side treats the other's output as already valid.
- */
-export const MEDIA_LAMBDA_REQUEST = "hypit.media-lambda-request@1";
-export const MEDIA_LAMBDA_RESPONSE = "hypit.media-lambda-response@1";
-
-export const mediaLambdaOperations = [
- "inspect",
- "normalize",
- "transform",
- "extract-audio",
- "extract-frame",
- "render-still",
- "project-speech-evidence-audio",
- "render-audio",
- "mux",
-] as const;
-
-export type MediaLambdaOperation = (typeof mediaLambdaOperations)[number];
-
-/**
- * The bucket the function reads sources from and writes results to.
- *
- * A synchronous invocation carries at most a few megabytes, so media never
- * travels in the payload — only the location it already occupies. This is why
- * the AWS media Provider requires an S3 ArtifactStore rather than merely
- * preferring one.
- */
-export type MediaLambdaArtifactLocation = {
- readonly bucket: string;
- readonly prefix?: string;
-};
-
-export type MediaLambdaRequest = {
- readonly contract: typeof MEDIA_LAMBDA_REQUEST;
- readonly operation: MediaLambdaOperation;
- readonly artifacts: MediaLambdaArtifactLocation;
- /** The Need's constraints, verbatim. The function validates them itself. */
- readonly constraints: CanonicalValue;
-};
-
-export type MediaLambdaResponse =
- | {
- readonly contract: typeof MEDIA_LAMBDA_RESPONSE;
- readonly operation: MediaLambdaOperation;
- readonly ok: true;
- readonly value: StoredValue;
- }
- | {
- readonly contract: typeof MEDIA_LAMBDA_RESPONSE;
- readonly operation: MediaLambdaOperation;
- readonly ok: false;
- readonly code: string;
- readonly message: string;
- };
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-function object(value: unknown, subject: string): Record<string, unknown> {
- assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
- return value as Record<string, unknown>;
-}
-
-function nonEmptyString(value: unknown, subject: string): string {
- assert(typeof value === "string" && value.trim().length > 0, `${subject} must be a non-empty string`);
- return value;
-}
-
-function operation(value: unknown, subject: string): MediaLambdaOperation {
- assert(typeof value === "string" && (mediaLambdaOperations as readonly string[]).includes(value),
- `${subject} must be one of ${mediaLambdaOperations.join(", ")}`);
- return value as MediaLambdaOperation;
-}
-
-function storedValue(value: unknown, subject: string): StoredValue {
- const item = object(value, subject);
- if (item.kind === "inline") {
- assert(item.value !== null && typeof item.value === "object", `${subject}.value must be canonical data`);
- return item as unknown as StoredValue;
- }
- assert(item.kind === "blob" && typeof item.digest === "string"
- && Number.isSafeInteger(item.size) && (item.size as number) >= 0
- && typeof item.mediaType === "string" && item.mediaType.length > 0,
- `${subject} must be an inline or blob StoredValue`);
- return item as unknown as StoredValue;
-}
-
-export function sealMediaLambdaRequest(request: MediaLambdaRequest): CanonicalValue {
- parseMediaLambdaRequest(request);
- return canonicalize(request as unknown as CanonicalValue);
-}
-
-/** Used by the function on every invocation. */
-export function parseMediaLambdaRequest(value: unknown): MediaLambdaRequest {
- const item = object(value, "MediaLambdaRequest");
- assert(item.contract === MEDIA_LAMBDA_REQUEST,
- `MediaLambdaRequest contract must be ${MEDIA_LAMBDA_REQUEST}`);
- const artifacts = object(item.artifacts, "MediaLambdaRequest.artifacts");
- const prefix = artifacts.prefix;
- assert(prefix === undefined || typeof prefix === "string",
- "MediaLambdaRequest.artifacts.prefix must be a string when present");
- assert(item.constraints !== null && typeof item.constraints === "object",
- "MediaLambdaRequest.constraints must be an object");
- return {
- contract: MEDIA_LAMBDA_REQUEST,
- operation: operation(item.operation, "MediaLambdaRequest.operation"),
- artifacts: {
- bucket: nonEmptyString(artifacts.bucket, "MediaLambdaRequest.artifacts.bucket"),
- ...(prefix === undefined || prefix.length === 0 ? {} : { prefix }),
- },
- constraints: item.constraints as CanonicalValue,
- };
-}
-
-/**
- * Used by the Endpoint on every reply.
- *
- * Failures arrive here rather than as a Lambda FunctionError, because the
- * transport deliberately refuses to copy a failed function's payload into its
- * error — that payload may carry deployment detail. A function that only threw
- * would reach the Endpoint as the word "Unhandled".
- */
-export function parseMediaLambdaResponse(value: unknown): MediaLambdaResponse {
- const item = object(value, "MediaLambdaResponse");
- assert(item.contract === MEDIA_LAMBDA_RESPONSE,
- `MediaLambdaResponse contract must be ${MEDIA_LAMBDA_RESPONSE}`);
- const named = operation(item.operation, "MediaLambdaResponse.operation");
- if (item.ok === false) {
- return {
- contract: MEDIA_LAMBDA_RESPONSE,
- operation: named,
- ok: false,
- code: nonEmptyString(item.code, "MediaLambdaResponse.code"),
- message: nonEmptyString(item.message, "MediaLambdaResponse.message"),
- };
- }
- assert(item.ok === true, "MediaLambdaResponse.ok must be a boolean");
- return {
- contract: MEDIA_LAMBDA_RESPONSE,
- operation: named,
- ok: true,
- value: storedValue(item.value, "MediaLambdaResponse.value"),
- };
-}
diff --git a/packages/provider-media-aws-lambda/src/index.ts b/packages/provider-media-aws-lambda/src/index.ts
deleted file mode 100644
index 617b53b1..00000000
--- a/packages/provider-media-aws-lambda/src/index.ts
+++ /dev/null
@@ -1,11 +0,0 @@
-export { awsLambdaMediaProviderModuleRef, createAwsLambdaMediaProvider } from "./provider.js";
-export {
- MEDIA_LAMBDA_REQUEST,
- MEDIA_LAMBDA_RESPONSE,
- mediaLambdaOperations,
- parseMediaLambdaRequest,
- parseMediaLambdaResponse,
- sealMediaLambdaRequest,
-} from "./contract.js";
-export type * from "./contract.js";
-export type { CreateAwsLambdaMediaProviderOptions } from "./provider.js";
diff --git a/packages/provider-media-aws-lambda/src/provider.ts b/packages/provider-media-aws-lambda/src/provider.ts
deleted file mode 100644
index 869dd925..00000000
--- a/packages/provider-media-aws-lambda/src/provider.ts
+++ /dev/null
@@ -1,174 +0,0 @@
-import { mediaTypes } from "@hypit/media";
-import { artifactTypes } from "@hypit/artifact";
-import { mediaPipelineCapabilities } from "@hypit/media-pipeline";
-import { canonicalize } from "@hypit/protocol";
-import type { BlobRef, CanonicalValue } from "@hypit/protocol";
-import { speechTypes } from "@hypit/speech";
-import { defineEndpointPackage } from "@hypit/endpoint-kit";
-import type { EndpointFulfillment, EndpointInvocationContext } from "@hypit/endpoint-kit";
-import { AwsLambdaJsonInvoker } from "@hypit/transport-aws-lambda";
-import type { JsonInvoker } from "@hypit/transport-aws-lambda";
-
-import {
- MEDIA_LAMBDA_REQUEST,
- parseMediaLambdaResponse,
- sealMediaLambdaRequest,
-} from "./contract.js";
-import type { MediaLambdaOperation } from "./contract.js";
-
-export const awsLambdaMediaProviderModuleRef = {
- name: "@hypit/provider-media-aws-lambda",
- version: "1",
-} as const;
-
-/** `arn:aws:lambda:<region>:<account>:function:<name>:<version|alias>` */
-const QUALIFIED_ARN =
- /^arn:aws:lambda:([a-z0-9-]+):\d{12}:function:[A-Za-z0-9-_]+:(\$LATEST|[A-Za-z0-9-_]+)$/u;
-
-export type CreateAwsLambdaMediaProviderOptions = {
- readonly instance?: string;
- readonly pool?: string;
- /** Must name a version or alias. See the assertion below for why. */
- readonly functionArn: string;
- readonly bucket: string;
- readonly prefix?: string;
- readonly region?: string;
- readonly defaultConcurrency?: number;
- /** Injection point for tests and specially configured trusted AWS clients. */
- readonly invoker?: JsonInvoker;
-};
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-function isBlobRef(value: unknown): value is BlobRef {
- return value !== null && typeof value === "object" && !Array.isArray(value)
- && (value as Record<string, unknown>).kind === "blob"
- && typeof (value as Record<string, unknown>).digest === "string";
-}
-
-/** Every Artifact the function claims to have written, at any depth of the result. */
-function producedArtifacts(value: unknown, found: BlobRef[] = []): readonly BlobRef[] {
- if (isBlobRef(value)) found.push(value);
- else if (Array.isArray(value)) for (const item of value) producedArtifacts(item, found);
- else if (value !== null && typeof value === "object") {
- for (const item of Object.values(value)) producedArtifacts(item, found);
- }
- return found;
-}
-
-export function createAwsLambdaMediaProvider(config: CreateAwsLambdaMediaProviderOptions) {
- // A function name without a version is whatever was deployed most recently.
- // Two Builds of one Run Source could then be executed by different code while
- // recording the same Endpoint identity, which is the one thing a BuildPlan
- // must never allow.
- const arn = QUALIFIED_ARN.exec(config.functionArn);
- assert(arn !== null,
- `Lambda functionArn must name a version or alias, as arn:aws:lambda:<region>:<account>:function:<name>:<version>; got ${config.functionArn}`);
- const region = config.region ?? arn[1]!;
- assert(region === arn[1],
- `Lambda region ${region} differs from the region in its ARN (${arn[1]})`);
- assert(config.bucket.trim().length > 0, "Lambda media Provider requires the ArtifactStore bucket");
-
- const configuration = {
- functionArn: config.functionArn,
- region,
- bucket: config.bucket,
- ...(config.prefix === undefined || config.prefix.length === 0 ? {} : { prefix: config.prefix }),
- };
- const invoker = config.invoker ?? new AwsLambdaJsonInvoker({
- functionName: config.functionArn,
- region,
- });
-
- const operation = (name: MediaLambdaOperation) =>
- async (context: EndpointInvocationContext): Promise<EndpointFulfillment> => {
- const reply = parseMediaLambdaResponse(await invoker.invoke(sealMediaLambdaRequest({
- contract: MEDIA_LAMBDA_REQUEST,
- operation: name,
- artifacts: {
- bucket: config.bucket,
- ...(config.prefix === undefined || config.prefix.length === 0 ? {} : { prefix: config.prefix }),
- },
- constraints: context.need.constraints,
- })));
- if (!reply.ok) throw new Error(`AWS media ${name} failed (${reply.code}): ${reply.message}`);
-
- // The function wrote its results straight into the bucket, so nothing was
- // uploaded here. Reading each one back through this Build's own
- // ArtifactStore is what proves the two were ever pointed at the same
- // place: a Provider configured against a different bucket fails here,
- // naming the Artifact, instead of yielding a Record that cannot be read.
- for (const artifact of producedArtifacts(reply.value)) {
- assert(await context.artifacts.has(artifact.digest),
- `AWS media ${name} reported Artifact ${artifact.digest}, which this Build's ArtifactStore cannot read`
- + ` — the Provider's bucket and the ArtifactStore's bucket are probably not the same`);
- }
- return { value: reply.value };
- };
-
- return defineEndpointPackage({
- module: awsLambdaMediaProviderModuleRef,
- facet: "media",
- instance: config.instance ?? "media.aws-lambda",
- pool: config.pool ?? config.instance ?? "media.aws-lambda",
- defaultConcurrency: config.defaultConcurrency ?? 8,
- capabilities: [
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.inspect,
- returns: mediaTypes.inspection,
- handler: operation("inspect"),
- },
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.normalize,
- returns: mediaTypes.synchronized,
- handler: operation("normalize"),
- },
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.transform,
- returns: artifactTypes.blob,
- handler: operation("transform"),
- },
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.extractAudio,
- returns: artifactTypes.blob,
- handler: operation("extract-audio"),
- },
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.extractFrame,
- returns: artifactTypes.blob,
- handler: operation("extract-frame"),
- },
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.renderStill,
- returns: artifactTypes.blob,
- handler: operation("render-still"),
- },
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.projectSpeechEvidenceAudio,
- returns: speechTypes.evidenceAudio,
- handler: operation("project-speech-evidence-audio"),
- },
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.renderAudio,
- returns: mediaTypes.timelineAudio,
- handler: operation("render-audio"),
- },
- {
- lifecycle: "immediate" as const,
- capability: mediaPipelineCapabilities.mux,
- returns: mediaTypes.muxed,
- handler: operation("mux"),
- },
- ],
- });
-}
diff --git a/packages/provider-media-aws-lambda/test/provider.test.ts b/packages/provider-media-aws-lambda/test/provider.test.ts
deleted file mode 100644
index b768e943..00000000
--- a/packages/provider-media-aws-lambda/test/provider.test.ts
+++ /dev/null
@@ -1,192 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
-
-import { MemoryArtifactStore } from "@hypit/driver-node";
-import { canonicalize } from "@hypit/protocol";
-import type { CanonicalValue } from "@hypit/protocol";
-import type { ImmediateEndpointHandler } from "@hypit/endpoint-kit";
-import type { JsonInvoker } from "@hypit/transport-aws-lambda";
-
-import {
- createAwsLambdaMediaProvider,
- parseMediaLambdaRequest,
- parseMediaLambdaResponse,
-} from "@hypit/provider-media-aws-lambda";
-
-const ARN = "arn:aws:lambda:us-east-1:123456789012:function:hypit-media:7";
-
-function recordingInvoker(reply: (request: CanonicalValue) => CanonicalValue) {
- const seen: CanonicalValue[] = [];
- const invoker: JsonInvoker = {
- invoke: async (request) => {
- seen.push(request);
- return reply(request);
- },
- };
- return { invoker, seen };
-}
-
-const inspectNeed = {
- source: { kind: "blob", digest: fixtureDigest("source"), size: 4, mediaType: "video/mp4" },
-} as unknown as CanonicalValue;
-
-/** Installs the Provider into a registrar that keeps the handlers, as the Runtime does. */
-async function endpointFor(invoker: JsonInvoker, options: { bucket?: string; capability?: string } = {}) {
- const provider = createAwsLambdaMediaProvider({
- functionArn: ARN,
- bucket: options.bucket ?? "team-artifacts",
- prefix: "svml",
- invoker,
- });
- const handlers = new Map<string, ImmediateEndpointHandler>();
- await provider.install({
- registerImmediateEndpoint: (
- _id: string,
- capability: { name: string },
- _returns: unknown,
- handler: ImmediateEndpointHandler,
- ) => {
- handlers.set(capability.name, handler);
- },
- registerAsyncEndpoint: () => {
- throw new Error("the AWS media Provider registers no asynchronous endpoint");
- },
- } as never);
- const capability = options.capability ?? "inspect-media";
- const handler = handlers.get(capability);
- assert.ok(handler, `the Provider offers ${capability}`);
- return { handler };
-}
-
-test("an unqualified function ARN is refused, because two Builds could then run different code", () => {
- assert.throws(
- () => createAwsLambdaMediaProvider({
- functionArn: "arn:aws:lambda:us-east-1:123456789012:function:hypit-media",
- bucket: "team-artifacts",
- }),
- /must name a version or alias/u,
- );
- assert.throws(
- () => createAwsLambdaMediaProvider({ functionArn: ARN, bucket: "team-artifacts", region: "eu-west-1" }),
- /differs from the region in its ARN/u,
- );
-});
-
-test("the Provider sends the Need verbatim with the bucket the function should use", async () => {
- const store = new MemoryArtifactStore();
- const artifact = await store.put(new TextEncoder().encode("out!"), "video/mp4");
- const { invoker, seen } = recordingInvoker(() => canonicalize({
- contract: "hypit.media-lambda-response@1",
- operation: "inspect",
- ok: true,
- value: { kind: "inline", value: { artifact } },
- } as unknown as CanonicalValue));
-
- const capability = await endpointFor(invoker);
- const outcome = await capability.handler({
- need: { constraints: inspectNeed },
- artifacts: store,
- credentials: {},
- } as never);
-
- const request = parseMediaLambdaRequest(seen[0]);
- assert.equal(request.operation, "inspect");
- assert.deepEqual(request.artifacts, { bucket: "team-artifacts", prefix: "svml" });
- assert.deepEqual(request.constraints, canonicalize(inspectNeed));
-});
-
-test("the remote Provider receives the exact AudioProgramPlan compiled for local execution", async () => {
- const store = new MemoryArtifactStore();
- const output = await store.put(new TextEncoder().encode("timeline-audio"), "audio/wav");
- const plan = canonicalize({
- frameRate: { numerator: 30_000, denominator: 1_001 },
- frameCount: 30,
- sampleRate: 48_000,
- sampleFrames: 48_048,
- clips: [{
- id: "end-loop",
- artifact: { kind: "blob", digest: fixtureDigest("audio-source"), size: 400, mediaType: "audio/wav" },
- targetStartSample: 0,
- targetEndSampleExclusive: 48_048,
- sourceSampleFrames: 20_000,
- sourceStartSample: 1_000,
- sourceEndSampleExclusive: 19_000,
- sourceLoop: true,
- sourcePhaseSample: 12_048,
- playbackRate: 1,
- pitch: "preserve",
- gain: 0.5,
- fadeInSamples: 480,
- fadeOutSamples: 960,
- }],
- mix: { normalize: false, limiter: "none" },
- } as unknown as CanonicalValue);
- const constraints = canonicalize({
- plan,
- } as unknown as CanonicalValue);
- const { invoker, seen } = recordingInvoker(() => canonicalize({
- contract: "hypit.media-lambda-response@1",
- operation: "render-audio",
- ok: true,
- value: { kind: "inline", value: {
- artifact: output, sampleFrames: 48_048,
- } },
- } as unknown as CanonicalValue));
- const capability = await endpointFor(invoker, { capability: "render-timeline-audio" });
- await capability.handler({ need: { constraints }, artifacts: store, credentials: {} } as never);
- const request = parseMediaLambdaRequest(seen[0]);
- assert.equal(request.operation, "render-audio");
- assert.deepEqual(request.constraints, constraints);
-});
-
-test("a Provider aimed at another bucket fails naming the Artifact, not later with an unreadable Record", async () => {
- const store = new MemoryArtifactStore();
- const stranger = fixtureDigest("an artifact this Build's store never received");
- const { invoker } = recordingInvoker(() => canonicalize({
- contract: "hypit.media-lambda-response@1",
- operation: "inspect",
- ok: true,
- value: { kind: "inline", value: {
- artifact: { kind: "blob", digest: stranger, size: 1, mediaType: "video/mp4" },
- } },
- } as unknown as CanonicalValue));
-
- await assert.rejects(
- async () => await (await endpointFor(invoker)).handler({
- need: { constraints: inspectNeed }, artifacts: store, credentials: {},
- } as never),
- (error: Error) => {
- assert.match(error.message, new RegExp(stranger, "u"));
- assert.match(error.message, /bucket and the ArtifactStore's bucket are probably not the same/u);
- return true;
- },
- );
-});
-
-test("a typed failure reaches the Build with its code, since the transport withholds the payload", async () => {
- const { invoker } = recordingInvoker(() => canonicalize({
- contract: "hypit.media-lambda-response@1",
- operation: "inspect",
- ok: false,
- code: "MEDIA_SOURCE_UNAVAILABLE",
- message: "source sha256:… is absent from bucket team-artifacts",
- } as unknown as CanonicalValue));
-
- await assert.rejects(
- async () => await (await endpointFor(invoker)).handler({
- need: { constraints: inspectNeed }, artifacts: new MemoryArtifactStore(), credentials: {},
- } as never),
- /MEDIA_SOURCE_UNAVAILABLE.*absent from bucket/su,
- );
-});
-
-test("a reply that is not this contract is refused rather than half-read", () => {
- assert.throws(() => parseMediaLambdaResponse({ contract: "hypit.media-lambda-response@invalid", operation: "inspect" }),
- /contract must be hypit\.media-lambda-response@1/u);
- assert.throws(() => parseMediaLambdaResponse({ contract: "hypit.media-lambda-response@1", operation: "transcode" }),
- /operation must be one of/u);
- assert.throws(() => parseMediaLambdaRequest({
- contract: "hypit.media-lambda-request@1", operation: "mux", artifacts: {}, constraints: {},
- }), /artifacts\.bucket must be a non-empty string/u);
-});
diff --git a/packages/provider-media-local/src/provider.ts b/packages/provider-media-local/src/provider.ts
index 482bcace..029b7db7 100644
--- a/packages/provider-media-local/src/provider.ts
+++ b/packages/provider-media-local/src/provider.ts
@@ -17,7 +17,7 @@ import {
import type { MediaExecutionEnvironment, MediaOperationResult } from "@hypit/media-execution";
import { mediaPipelineCapabilities } from "@hypit/media-pipeline";
import { mockMediaCapabilities } from "@hypit/mock-media";
-import { isStreamingArtifactStore } from "@hypit/runtime";
+import { isStreamingResourceStore } from "@hypit/runtime";
import { speechTypes } from "@hypit/speech";
import { defineEndpointPackage } from "@hypit/endpoint-kit";
import type { EndpointFulfillment, EndpointInvocationContext } from "@hypit/endpoint-kit";
@@ -48,7 +48,7 @@ function fulfillment(result: MediaOperationResult): EndpointFulfillment {
}
/**
- * The Build's own ArtifactStore, and whatever ffmpeg this machine has. The
+ * The Build's own ResourceStore, and whatever ffmpeg this machine has. The
* operations themselves live in `@hypit/media-execution`, shared with the
* AWS Provider so one Need cannot mean two different transforms.
*/
@@ -62,16 +62,16 @@ export function createLocalMediaProvider(config: CreateLocalMediaProviderOptions
const environment = (context: EndpointInvocationContext): MediaExecutionEnvironment => ({
...common,
artifacts: {
- get: async (source) => await context.artifacts.get(source.digest),
- open: async (source) => isStreamingArtifactStore(context.artifacts)
- ? await context.artifacts.open(source.digest)
- : await context.artifacts.get(source.digest).then((bytes) => bytes === undefined
+ get: async (source) => await context.resources.get(source.resource),
+ open: async (source) => isStreamingResourceStore(context.resources)
+ ? await context.resources.open(source.resource)
+ : await context.resources.get(source.resource).then((bytes) => bytes === undefined
? undefined
: (async function* () { yield bytes; })()),
- put: async (bytes, mediaType) => await context.artifacts.put(bytes, mediaType),
- putFile: async (path, mediaType) => isStreamingArtifactStore(context.artifacts)
- ? await context.artifacts.putStream(createReadStream(path), mediaType)
- : await context.artifacts.put(await readFile(path), mediaType),
+ put: async (bytes, mediaType) => await context.resources.put(bytes, mediaType),
+ putFile: async (path, mediaType) => isStreamingResourceStore(context.resources)
+ ? await context.resources.putStream(createReadStream(path), mediaType)
+ : await context.resources.put(await readFile(path), mediaType),
},
});
const operation = (
diff --git a/packages/provider-media-local/test/provider.test.ts b/packages/provider-media-local/test/provider.test.ts
index 4da3d5af..c2ea3c35 100644
--- a/packages/provider-media-local/test/provider.test.ts
+++ b/packages/provider-media-local/test/provider.test.ts
@@ -10,7 +10,7 @@ import { assertSpeechEvidenceAudioIdentity, speechTypes } from "@hypit/speech";
import type { SpeechEvidenceAudio } from "@hypit/speech";
import assert from "node:assert/strict";
import {
- MemoryArtifactStore,
+ MemoryResourceStore,
EndpointRegistry,
} from "@hypit/driver-node";
import type { EndpointRegistration } from "@hypit/driver-node";
@@ -163,12 +163,12 @@ function need(
};
}
-async function fulfillInline(artifacts: MemoryArtifactStore, request: Need): Promise<CanonicalValue> {
+async function fulfillInline(resources: MemoryResourceStore, request: Need): Promise<CanonicalValue> {
const provider = await handlerFor(request);
const result = await provider.handler({
command: { kind: "fulfill-need", id: `command:${request.id}`, need: request },
need: request,
- artifacts,
+ resources,
credentials: {},
});
assert.equal(result.value.kind, "inline");
@@ -184,7 +184,7 @@ async function handlerFor(request: Need): Promise<{ handler: ImmediateEndpointHa
return { handler: resolution.registration.handler, registration: resolution.registration };
}
-async function inspectArtifact(artifacts: MemoryArtifactStore, source: Awaited<ReturnType<MemoryArtifactStore["put"]>>) {
+async function inspectArtifact(resources: MemoryResourceStore, source: Awaited<ReturnType<MemoryResourceStore["put"]>>) {
const constraints = canonicalize({ source });
const request = need("need:media-inspect", mediaPipelineCapabilities.inspect,
mediaTypes.inspection, constraints);
@@ -192,7 +192,7 @@ async function inspectArtifact(artifacts: MemoryArtifactStore, source: Awaited<R
const result = await provider.handler({
command: { kind: "fulfill-need", id: "command:media-inspect", need: request },
need: request,
- artifacts,
+ resources,
credentials: {},
});
assert.equal(result.value.kind, "inline");
@@ -202,8 +202,8 @@ async function inspectArtifact(artifacts: MemoryArtifactStore, source: Awaited<R
}
async function normalizeArtifact(args: {
- artifacts: MemoryArtifactStore;
- source: Awaited<ReturnType<MemoryArtifactStore["put"]>>;
+ resources: MemoryResourceStore;
+ source: Awaited<ReturnType<MemoryResourceStore["put"]>>;
inspection: MediaInspection;
selection: ReturnType<typeof selectMediaStreams>;
frameRate: { readonly numerator: number; readonly denominator: number };
@@ -221,7 +221,7 @@ async function normalizeArtifact(args: {
const result = await provider.handler({
command: { kind: "fulfill-need", id: "command:media-normalize", need: request },
need: request,
- artifacts: args.artifacts,
+ resources: args.resources,
credentials: {},
});
assert.equal(result.value.kind, "inline");
@@ -236,9 +236,9 @@ test("local media Provider enumerates attached pictures and jointly normalizes 3
const root = await mkdtemp(join(tmpdir(), "hypit-provider-media-local-"));
try {
const sourcePath = await fixture(root);
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(await readFile(sourcePath), "video/mp4");
- const typedInspection = await inspectArtifact(artifacts, source);
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(await readFile(sourcePath), "video/mp4");
+ const typedInspection = await inspectArtifact(resources, source);
assert.deepEqual(typedInspection.streams.map((stream) => [stream.index, stream.kind,
stream.kind === "video" ? stream.role : stream.codecName]), [
[0, "video", "moving"],
@@ -257,16 +257,16 @@ test("local media Provider enumerates attached pictures and jointly normalizes 3
const selection = selectMediaStreams(typedInspection, selectionRequest);
assert.equal(selection.videoStreamIndex, 0);
assert.equal(selection.audioStreamIndex, 1);
- const typed = await normalizeArtifact({ artifacts, source, inspection: typedInspection,
+ const typed = await normalizeArtifact({ resources, source, inspection: typedInspection,
selection, frameRate: selectionRequest.frameRate });
assert.equal(typed.timeline.frameCount, 30);
assert.equal(synchronizedMediaSampleFrames(typed), 48_000);
- assert.equal("basisDigest" in typed, false);
+ assert.equal("basisResourceId" in typed, false);
assert.equal("narrativeDigest" in typed, false);
- assert.equal(await artifacts.has(typed.visual!.artifact.digest), true);
- assert.equal(await artifacts.has(typed.audio!.artifact.digest), true);
+ assert.equal(await resources.has(typed.visual!.artifact.resource), true);
+ assert.equal(await resources.has(typed.audio!.artifact.resource), true);
- const visualBytes = await artifacts.get(typed.visual!.artifact.digest);
+ const visualBytes = await resources.get(typed.visual!.artifact.resource);
assert(visualBytes !== undefined);
const visualPath = join(root, "normalized-visual.mp4");
await writeFile(visualPath, visualBytes);
@@ -294,7 +294,7 @@ test("local media Provider enumerates attached pictures and jointly normalizes 3
};
assert.deepEqual(outputProbe.streams.map((stream) => stream.codec_type), ["video"]);
assert.equal(outputProbe.streams[0]?.nb_frames, "30");
- const audioOutput = await inspectArtifact(artifacts, typed.audio!.artifact);
+ const audioOutput = await inspectArtifact(resources, typed.audio!.artifact);
const normalizedAudio = audioOutput.streams.find((stream) => stream.kind === "audio");
assert.equal(normalizedAudio?.kind === "audio" && normalizedAudio.sampleRate, 48_000);
assert.equal(normalizedAudio?.kind === "audio" && normalizedAudio.channels, 2);
@@ -318,9 +318,9 @@ test("local media normalization materializes rotation and sample aspect before S
await run("ffmpeg", [
"-v", "error", "-y", "-display_rotation", "90", "-i", base, "-c", "copy", sourcePath,
]);
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(await readFile(sourcePath), "video/mp4");
- const inspection = await inspectArtifact(artifacts, source);
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(await readFile(sourcePath), "video/mp4");
+ const inspection = await inspectArtifact(resources, source);
const inputVideo = inspection.streams.find((stream) => stream.kind === "video");
assert.equal(inputVideo?.kind, "video");
if (inputVideo?.kind !== "video") return;
@@ -331,10 +331,10 @@ test("local media normalization materializes rotation and sample aspect before S
spanAuthority: "video", frameRate: { numerator: 4, denominator: 1 },
});
const selection = selectMediaStreams(inspection, request);
- const normalized = await normalizeArtifact({ artifacts, source, inspection, selection, frameRate: request.frameRate });
+ const normalized = await normalizeArtifact({ resources, source, inspection, selection, frameRate: request.frameRate });
assert.equal(normalized.visual?.width, 96);
assert.equal(normalized.visual?.height, 320);
- const output = await inspectArtifact(artifacts, normalized.visual!.artifact);
+ const output = await inspectArtifact(resources, normalized.visual!.artifact);
const outputVideo = output.streams.find((stream) => stream.kind === "video");
assert.equal(outputVideo?.kind, "video");
if (outputVideo?.kind !== "video") return;
@@ -348,9 +348,9 @@ test("local media normalization materializes rotation and sample aspect before S
test("animated WebP keeps its authored frame timing before fixed-rate normalization", {
skip: !hasMediaBinaries,
}, async () => {
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(animatedWebp, "image/webp");
- const inspection = await inspectArtifact(artifacts, source);
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(animatedWebp, "image/webp");
+ const inspection = await inspectArtifact(resources, source);
assert.deepEqual(inspection.container.formatNames, ["webp", "webp-animation"]);
assert.deepEqual(inspection.streams.map((stream) => [stream.kind, stream.kind === "video" ? stream.role : undefined,
stream.decodedUnitCount]), [["video", "moving", 5]]);
@@ -365,11 +365,11 @@ test("animated WebP keeps its authored frame timing before fixed-rate normalizat
frameRate: { numerator: 20, denominator: 1 },
});
const selection = selectMediaStreams(inspection, request);
- const normalized = await normalizeArtifact({ artifacts, source, inspection, selection, frameRate: request.frameRate });
+ const normalized = await normalizeArtifact({ resources, source, inspection, selection, frameRate: request.frameRate });
assert.equal(normalized.timeline.frameCount, 10);
assert.equal(normalized.visual?.width, 64);
assert.equal(normalized.visual?.height, 48);
- const output = await inspectArtifact(artifacts, normalized.visual!.artifact);
+ const output = await inspectArtifact(resources, normalized.visual!.artifact);
assert.equal(output.streams[0]?.decodedUnitCount, 10);
});
@@ -383,9 +383,9 @@ test("animated GIF keeps its authored frame timing before fixed-rate normalizati
"-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=s=64x48:r=10:d=0.5",
"-frames:v", "5", path,
]);
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(await readFile(path), "image/gif");
- const inspection = await inspectArtifact(artifacts, source);
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(await readFile(path), "image/gif");
+ const inspection = await inspectArtifact(resources, source);
assert.deepEqual(inspection.streams.map((stream) => [stream.kind, stream.kind === "video" ? stream.role : undefined,
stream.decodedUnitCount]), [["video", "moving", 5]]);
const request = sealMediaSelectionRequest({
@@ -395,9 +395,9 @@ test("animated GIF keeps its authored frame timing before fixed-rate normalizati
frameRate: { numerator: 20, denominator: 1 },
});
const selection = selectMediaStreams(inspection, request);
- const normalized = await normalizeArtifact({ artifacts, source, inspection, selection, frameRate: request.frameRate });
+ const normalized = await normalizeArtifact({ resources, source, inspection, selection, frameRate: request.frameRate });
assert.equal(normalized.timeline.frameCount, 10);
- const output = await inspectArtifact(artifacts, normalized.visual!.artifact);
+ const output = await inspectArtifact(resources, normalized.visual!.artifact);
assert.equal(output.streams[0]?.decodedUnitCount, 10);
} finally {
await rm(root, { recursive: true, force: true });
@@ -416,8 +416,8 @@ test("local media Provider derives one exact 16 kHz mono WhisperX evidence artif
"-af", "atrim=start_sample=0:end_sample=48001,asetpts=N/SR/TB,aformat=sample_rates=48000:channel_layouts=stereo",
"-c:a", "pcm_s16le", "-ar", "48000", "-ac", "2", sourcePath,
]);
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(await readFile(sourcePath), "audio/wav");
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(await readFile(sourcePath), "audio/wav");
const constraints = canonicalize({
source,
sourceSampleFrames: 48_001,
@@ -429,11 +429,11 @@ test("local media Provider derives one exact 16 kHz mono WhisperX evidence artif
speechTypes.evidenceAudio,
constraints,
);
- const value = await fulfillInline(artifacts, request);
+ const value = await fulfillInline(resources, request);
assertSpeechEvidenceAudioIdentity(value as unknown as SpeechEvidenceAudio);
const evidence = value as unknown as SpeechEvidenceAudio;
assert.equal(evidence.sampleFrames, 16_000);
- const inspected = await inspectArtifact(artifacts, evidence.artifact);
+ const inspected = await inspectArtifact(resources, evidence.artifact);
const audio = inspected.streams.find((stream) => stream.kind === "audio");
assert.equal(audio?.kind, "audio");
assert.equal(audio?.kind === "audio" && audio.codecName, "pcm_s16le");
@@ -461,9 +461,9 @@ test("local media Provider preserves one source A/V origin when audio starts lat
"-c:a", "pcm_s16le", "-avoid_negative_ts", "disabled",
sourcePath,
]);
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(await readFile(sourcePath), "video/x-matroska");
- const inspection = await inspectArtifact(artifacts, source);
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(await readFile(sourcePath), "video/x-matroska");
+ const inspection = await inspectArtifact(resources, source);
const request = sealMediaSelectionRequest({
video: { mode: "primary-moving" },
audio: { mode: "default" },
@@ -471,7 +471,7 @@ test("local media Provider preserves one source A/V origin when audio starts lat
frameRate: { numerator: 30, denominator: 1 },
});
const selection = selectMediaStreams(inspection, request);
- const normalized = await normalizeArtifact({ artifacts, source, inspection, selection, frameRate: request.frameRate });
+ const normalized = await normalizeArtifact({ resources, source, inspection, selection, frameRate: request.frameRate });
const video = inspection.streams.find((stream) => stream.kind === "video" && stream.index === selection.videoStreamIndex)!;
const audio = inspection.streams.find((stream) => stream.kind === "audio" && stream.index === selection.audioStreamIndex)!;
assert(video.startPts !== undefined && audio.startPts !== undefined && audio.endPts !== undefined);
@@ -481,7 +481,7 @@ test("local media Provider preserves one source A/V origin when audio starts lat
const expectedEnd = Math.round((seconds(audio.endPts) - seconds(video.startPts)) * 48_000);
const expectedTail = 48_000 - Math.min(48_000, expectedEnd);
assert.equal(normalized.timeline.frameCount, 30);
- const bytes = await artifacts.get(normalized.audio!.artifact.digest);
+ const bytes = await resources.get(normalized.audio!.artifact.resource);
assert(bytes !== undefined);
const audible = pcm16StereoAudibleSpan(bytes);
assert.equal(audible.sampleFrames, 48_000);
@@ -504,9 +504,9 @@ test("a silent generated MP4 remains a visual-only product and cannot satisfy a
"-v", "error", "-y", "-f", "lavfi", "-i", "testsrc2=s=160x96:r=24:d=0.5",
"-frames:v", "12", "-c:v", "libx264", "-pix_fmt", "yuv420p", "-an", sourcePath,
]);
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(await readFile(sourcePath), "video/mp4");
- const inspection = await inspectArtifact(artifacts, source);
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(await readFile(sourcePath), "video/mp4");
+ const inspection = await inspectArtifact(resources, source);
const request = sealMediaSelectionRequest({
video: { mode: "primary-moving" },
audio: { mode: "none" },
@@ -514,7 +514,7 @@ test("a silent generated MP4 remains a visual-only product and cannot satisfy a
frameRate: { numerator: 30, denominator: 1 },
});
const selection = selectMediaStreams(inspection, request);
- const normalized = await normalizeArtifact({ artifacts, source, inspection, selection, frameRate: request.frameRate });
+ const normalized = await normalizeArtifact({ resources, source, inspection, selection, frameRate: request.frameRate });
assert.equal(normalized.timeline.frameCount, 15);
assert.ok(normalized.visual);
assert.equal(normalized.audio, undefined);
@@ -537,9 +537,9 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
const root = await mkdtemp(join(tmpdir(), "hypit-provider-media-ordinary-ops-"));
try {
const sourcePath = await fixture(root);
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(await readFile(sourcePath), "video/mp4");
- const inspection = await inspectArtifact(artifacts, source);
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(await readFile(sourcePath), "video/mp4");
+ const inspection = await inspectArtifact(resources, source);
const selectionRequest = sealMediaSelectionRequest({
video: { mode: "primary-moving" },
audio: { mode: "default" },
@@ -548,14 +548,14 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
});
const selection = selectMediaStreams(inspection, selectionRequest);
const normalized = await normalizeArtifact({
- artifacts, source, inspection, selection, frameRate: selectionRequest.frameRate,
+ resources, source, inspection, selection, frameRate: selectionRequest.frameRate,
});
const executeArtifact = async (request: Need) => {
const provider = await handlerFor(request);
const result = await provider.handler({
command: { kind: "fulfill-need", id: `command:${request.id}`, need: request },
need: request,
- artifacts,
+ resources,
credentials: {},
});
assert.equal(result.value.kind, "blob");
@@ -576,7 +576,7 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
},
}),
));
- const transformedInspection = await inspectArtifact(artifacts, transformed);
+ const transformedInspection = await inspectArtifact(resources, transformed);
assert.equal(transformedInspection.streams.find((item) => item.kind === "video")?.decodedUnitCount, 12);
const audioIndex = inspection.streams.find((item) => item.kind === "audio")!.index;
@@ -591,7 +591,7 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
}),
));
assert.equal(extractedAudio.mediaType, "audio/wav");
- const audioInspection = await inspectArtifact(artifacts, extractedAudio);
+ const audioInspection = await inspectArtifact(resources, extractedAudio);
const audio = audioInspection.streams.find((item) => item.kind === "audio");
assert.ok(audio?.kind === "audio" && audio.sampleRate === 48_000 && audio.channels === 2);
@@ -609,7 +609,7 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
}),
));
assert.equal(extractedFrame.mediaType, "image/png");
- const frameInspection = await inspectArtifact(artifacts, extractedFrame);
+ const frameInspection = await inspectArtifact(resources, extractedFrame);
assert.equal(frameInspection.streams.find((item) => item.kind === "video")?.decodedUnitCount, 1);
const stillVideo = await executeArtifact(need(
@@ -626,7 +626,7 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
}),
));
assert.equal(stillVideo.mediaType, "video/mp4");
- const stillInspection = await inspectArtifact(artifacts, stillVideo);
+ const stillInspection = await inspectArtifact(resources, stillVideo);
assert.equal(stillInspection.streams.length, 1);
assert.equal(stillInspection.streams[0]?.kind, "video");
assert.equal(stillInspection.streams[0]?.decodedUnitCount, 15);
@@ -637,7 +637,7 @@ test("local media Provider transforms A/V and extracts ordinary audio and frame
frameRate: { numerator: 30, denominator: 1 },
}));
const stillNormalized = await normalizeArtifact({
- artifacts,
+ resources,
source: stillVideo,
inspection: stillInspection,
selection: stillSelection,
@@ -675,11 +675,11 @@ test("local media Provider renders one frame-domain audio plan and muxes exactly
]),
]);
- const artifacts = new MemoryArtifactStore();
+ const resources = new MemoryResourceStore();
const [first, second, visualArtifact] = await Promise.all([
- artifacts.put(await readFile(firstPath), "audio/wav"),
- artifacts.put(await readFile(secondPath), "audio/wav"),
- artifacts.put(await readFile(visualPath), "video/mp4"),
+ resources.put(await readFile(firstPath), "audio/wav"),
+ resources.put(await readFile(secondPath), "audio/wav"),
+ resources.put(await readFile(visualPath), "video/mp4"),
]);
const plan = sealAudioProgramPlan({
frameRate: { numerator: 30, denominator: 1 },
@@ -728,11 +728,11 @@ test("local media Provider renders one frame-domain audio plan and muxes exactly
mediaTypes.timelineAudio,
canonicalize({ plan }),
);
- const audioValue = await fulfillInline(artifacts, audioRequest);
+ const audioValue = await fulfillInline(resources, audioRequest);
verifyTimelineAudio(audioValue);
const audio = audioValue as unknown as TimelineAudio;
assert.equal(audio.sampleFrames, 48_000);
- assert.equal(await artifacts.has(audio.artifact.digest), true);
+ assert.equal(await resources.has(audio.artifact.resource), true);
const visual = sealRenderedVisual({
frameRate: { numerator: 30, denominator: 1 },
@@ -746,13 +746,13 @@ test("local media Provider renders one frame-domain audio plan and muxes exactly
mediaTypes.muxed,
canonicalize({ visual, audio }),
);
- const muxValue = await fulfillInline(artifacts, muxRequest);
+ const muxValue = await fulfillInline(resources, muxRequest);
verifyMuxedMedia(muxValue);
const muxed = muxValue as unknown as MuxedMedia;
assert.equal(muxed.presentationSampleFrames, 48_000);
- assert.equal(await artifacts.has(muxed.artifact.digest), true);
+ assert.equal(await resources.has(muxed.artifact.resource), true);
- const inspection = await inspectArtifact(artifacts, muxed.artifact);
+ const inspection = await inspectArtifact(resources, muxed.artifact);
const videos = inspection.streams.filter((stream) => stream.kind === "video");
const audios = inspection.streams.filter((stream) => stream.kind === "audio");
assert.equal(inspection.streams.length, 2);
@@ -775,8 +775,8 @@ test("local media Provider executes an end-aligned loop from the exact authored
}, async () => {
const root = await mkdtemp(join(tmpdir(), "hypit-provider-media-loop-"));
try {
- const artifacts = new MemoryArtifactStore();
- const source = await artifacts.put(rampWav(100), "audio/wav");
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(rampWav(100), "audio/wav");
const plan = sealAudioProgramPlan({
frameRate: { numerator: 30, denominator: 1 },
frameCount: 30,
@@ -800,7 +800,7 @@ test("local media Provider executes an end-aligned loop from the exact authored
}],
mix: { normalize: false, limiter: "none" },
});
- const value = await fulfillInline(artifacts, need(
+ const value = await fulfillInline(resources, need(
"need:render-loop-audio",
mediaPipelineCapabilities.renderAudio,
mediaTypes.timelineAudio,
@@ -809,7 +809,7 @@ test("local media Provider executes an end-aligned loop from the exact authored
verifyTimelineAudio(value);
const audio = value as unknown as TimelineAudio;
assert.equal(audio.sampleFrames, 48_000);
- const wav = await artifacts.get(audio.artifact.digest);
+ const wav = await resources.get(audio.artifact.resource);
assert(wav);
const wavPath = join(root, "loop.wav");
const rawPath = join(root, "loop.raw");
diff --git a/packages/provider-vertex/src/provider.ts b/packages/provider-vertex/src/provider.ts
index 82c6d02c..b094443f 100644
--- a/packages/provider-vertex/src/provider.ts
+++ b/packages/provider-vertex/src/provider.ts
@@ -41,8 +41,8 @@ export function createVertexProvider(options: CreateVertexProviderOptions) {
});
const parts: Array<{ text: string } | { inlineData: { mimeType: string; data: string } }> = [{ text: typed.prompt }];
for (const item of typed.media) {
- const bytes = await context.artifacts.get(item.artifact.digest);
- if (bytes === undefined) throw new Error(`Vertex Gemini reference artifact ${item.artifact.digest} is unavailable`);
+ const bytes = await context.resources.get(item.artifact.resource);
+ if (bytes === undefined) throw new Error(`Vertex Gemini reference artifact ${item.artifact.resource} is unavailable`);
parts.push({ inlineData: { mimeType: item.artifact.mediaType, data: Buffer.from(bytes).toString("base64") } });
}
const value = await generate({ parts, instruction: typed.instruction });
diff --git a/packages/provider-whisperx-local/src/provider.ts b/packages/provider-whisperx-local/src/provider.ts
index 1be0a65a..a899aa86 100644
--- a/packages/provider-whisperx-local/src/provider.ts
+++ b/packages/provider-whisperx-local/src/provider.ts
@@ -241,9 +241,9 @@ export function createLocalWhisperXProvider(config: CreateLocalWhisperXProviderO
returns: speechEvidenceTypes.alignedTranscript,
handler: async (context: EndpointInvocationContext) => {
const request = alignmentRequest(context.need.constraints);
- const audio = await context.artifacts.get(request.audio.digest);
+ const audio = await context.resources.get(request.audio.resource);
assert(audio !== undefined && audio.byteLength === request.audio.size,
- `WhisperX evidence Artifact ${request.audio.digest} is unavailable or has changed`);
+ `WhisperX evidence Artifact ${request.audio.resource} is unavailable or has changed`);
assertCanonicalEvidenceWav(audio, request.sampleFrames);
const work = await mkdtemp(join(tmpdir(), "hypit-whisperx-local-"));
try {
diff --git a/packages/provider-whisperx-local/test/provider.test.ts b/packages/provider-whisperx-local/test/provider.test.ts
index 6aa5d567..746aef51 100644
--- a/packages/provider-whisperx-local/test/provider.test.ts
+++ b/packages/provider-whisperx-local/test/provider.test.ts
@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
import test from "node:test";
import { sealSpeechEvidenceAudio, speechTypes } from "@hypit/speech";
import assert from "node:assert/strict";
-import { MemoryArtifactStore, EndpointRegistry } from "@hypit/driver-node";
+import { MemoryResourceStore, EndpointRegistry } from "@hypit/driver-node";
import type { Need } from "@hypit/protocol";
import { speechEvidenceTypes } from "@hypit/speech-evidence";
import {
@@ -103,8 +103,8 @@ test("local Provider stages canonical evidence bytes unchanged and returns seale
}), { headers: { "content-type": "application/json" } });
}) as typeof fetch;
try {
- const artifacts = new MemoryArtifactStore();
- const artifact = await artifacts.put(expected, "audio/wav");
+ const resources = new MemoryResourceStore();
+ const artifact = await resources.put(expected, "audio/wav");
const evidenceAudio = sealSpeechEvidenceAudio({
artifact,
sampleFrames: 32_000,
@@ -129,7 +129,7 @@ test("local Provider stages canonical evidence bytes unchanged and returns seale
const output = await resolved.registration.handler({
command: { kind: "fulfill-need", id: "command:whisperx-loopback", need },
need,
- artifacts,
+ resources,
credentials: {},
});
assert.equal(stagedMatches, true);
diff --git a/packages/provider-xiaomi-mimo/README.md b/packages/provider-xiaomi-mimo/README.md
index cf1ea4b5..9ccac1cd 100644
--- a/packages/provider-xiaomi-mimo/README.md
+++ b/packages/provider-xiaomi-mimo/README.md
@@ -3,7 +3,7 @@
Immediate Runtime Endpoint for Xiaomi's official MiMo V2.5 VoiceDesign API.
This package owns the `chat/completions` wire shape, `api-key` credential, timeout, response bounds,
-and ArtifactStore ingestion. It does not import `@hypit/mimo-tts`: the VoiceDesign capability and
+and ResourceStore ingestion. It does not import `@hypit/mimo-tts`: the VoiceDesign capability and
port names are bound as versioned data, keeping the exact model contract independent from this service.
Runtime Profile example:
diff --git a/packages/provider-xiaomi-mimo/src/provider.ts b/packages/provider-xiaomi-mimo/src/provider.ts
index cb0e5849..5e98c1ca 100644
--- a/packages/provider-xiaomi-mimo/src/provider.ts
+++ b/packages/provider-xiaomi-mimo/src/provider.ts
@@ -157,7 +157,7 @@ export function createXiaomiMimoProvider(options: CreateXiaomiMimoProviderOption
}
if (!response.ok) throw new Error(`Xiaomi MiMo returned HTTP ${response.status}: ${responseText.slice(0, 300)}`);
const bytes = parseAudio(responseText, maxResponseBytes);
- const artifact = await context.artifacts.put(bytes, "audio/wav");
+ const artifact = await context.resources.put(bytes, "audio/wav");
const result = sealGeneratedAudioSet({ audios: [artifact] });
return { value: { kind: "inline" as const, value: result as unknown as CanonicalValue } };
},
diff --git a/packages/provider-xiaomi-mimo/test/provider.test.ts b/packages/provider-xiaomi-mimo/test/provider.test.ts
index 226a278f..4ef894e3 100644
--- a/packages/provider-xiaomi-mimo/test/provider.test.ts
+++ b/packages/provider-xiaomi-mimo/test/provider.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { EndpointRegistry, MemoryArtifactStore } from "@hypit/driver-node";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
import { generationTypes } from "@hypit/generation";
import { mimoTtsEndpoints, sealMimoTtsRequest } from "@hypit/mimo-tts";
import type { CanonicalValue, Need } from "@hypit/protocol";
@@ -18,7 +18,7 @@ function need(constraints: CanonicalValue): Need {
}
test("the official Provider maps only the VoiceDesign contract", async () => {
- const artifacts = new MemoryArtifactStore();
+ const resources = new MemoryResourceStore();
const provider = createXiaomiMimoProvider({
fetch: async (input, init) => {
assert.equal(String(input), "https://api.xiaomimimo.com/v1/chat/completions");
@@ -45,14 +45,14 @@ test("the official Provider maps only the VoiceDesign contract", async () => {
const result = await resolution.registration.handler({
command: { kind: "fulfill-need", id: "command:mimo-voicedesign", need: request },
need: request,
- artifacts,
+ resources,
credentials: { apiKey: { secret: "test-key" } },
});
assert.equal(result.value.kind, "inline");
const set = result.value.kind === "inline" ? result.value.value as Record<string, unknown> : {};
- const audios = set.audios as Array<{ mediaType: string; digest: string }>;
+ const audios = set.audios as Array<{ mediaType: string; resource: string }>;
assert.equal(audios[0]?.mediaType, "audio/wav");
- assert.equal(await artifacts.has(audios[0]!.digest as `sha256:${string}`), true);
+ assert.equal(await resources.has(audios[0]!.resource as `res_${string}`), true);
});
test("Provider configuration owns credentials and queue policy, not model semantics", () => {
diff --git a/packages/ranking-studio/src/index.ts b/packages/ranking-studio/src/index.ts
index f4d91b58..b3c02c03 100644
--- a/packages/ranking-studio/src/index.ts
+++ b/packages/ranking-studio/src/index.ts
@@ -136,7 +136,7 @@ function projectRanking(context: StudioTrackCompanionContext): readonly StudioEn
...(semanticSource?.id === undefined ? {} : { markerId: semanticSource.id }),
display: {
title: label,
- layers: icon === undefined ? [] : [previewLayer(artifactPreview("image", icon.digest), "repeat-x")],
+ layers: icon === undefined ? [] : [previewLayer(artifactPreview("image", icon.resource), "repeat-x")],
},
startFrame: visible.startFrame,
endFrameExclusive: visible.endFrameExclusive,
diff --git a/packages/ranking/src/schedule.ts b/packages/ranking/src/schedule.ts
index c4dc5d2d..ae905bff 100644
--- a/packages/ranking/src/schedule.ts
+++ b/packages/ranking/src/schedule.ts
@@ -8,7 +8,7 @@ import {
programSpaceFrameCount,
} from "@hypit/program-space";
import type { ProgramSpace } from "@hypit/program-space";
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import { verifyText } from "@hypit/text";
import type { Text } from "@hypit/text";
import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
@@ -96,8 +96,8 @@ function stacking(value: number, label: string): void {
assert(Number.isSafeInteger(value), `${label} must be an integer.`);
}
-function assertBlobImage(value: { readonly digest: string; readonly size: number; readonly mediaType: string }, label: string): void {
- assert(isDigest(value.digest) && Number.isSafeInteger(value.size) && value.size >= 0
+function assertBlobImage(value: { readonly resource: string; readonly size: number; readonly mediaType: string }, label: string): void {
+ assert(isResourceId(value.resource) && Number.isSafeInteger(value.size) && value.size >= 0
&& /^image\//u.test(value.mediaType), `${label} must be an image Artifact.`);
}
diff --git a/packages/ranking/test/ranking.test.ts b/packages/ranking/test/ranking.test.ts
index a66b15de..ee9f8821 100644
--- a/packages/ranking/test/ranking.test.ts
+++ b/packages/ranking/test/ranking.test.ts
@@ -1,7 +1,7 @@
import assert from "node:assert/strict";
import test from "node:test";
import { videoContractManifests } from "../../../test/support/video-domain.js";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import { projectMomentInstantFixture, projectSegmentWindow, projectSelectionWindow } from "../../../test/temporal-fixture.js";
@@ -148,14 +148,14 @@ const middle = selection("middle", "early-end", "overlap-end");
const late = selection("late", "late-start", "late-end");
const triggerAnchors = ["one", "two", "three", "four"] as const;
const font: FontArtifactRef = {
- sources: [{ artifact: { kind: "blob", digest: fixtureDigest("ranking-font"), size: 32, mediaType: "font/woff2" } }],
+ sources: [{ artifact: { kind: "blob", resource: fixtureResource("ranking-font"), size: 32, mediaType: "font/woff2" } }],
weight: 700,
style: "normal",
};
const recipe = (path: string, properties: SvsRecipe["properties"] = {}): SvsRecipe => ({
path, properties,
});
-const image = (id: string) => ({ kind: "blob" as const, digest: fixtureDigest(`ranking-image:${id}`), size: 64, mediaType: "image/png" });
+const image = (id: string) => ({ kind: "blob" as const, resource: fixtureResource(`ranking-image:${id}`), size: 64, mediaType: "image/png" });
const header = (variant: RankingHeader["variant"], id: string = variant) => sealRankingHeader({
id, variant,
});
@@ -315,7 +315,7 @@ test("variant Style decoders reject unknown Recipes and keep exact fonts and ind
rows: [{ id: "s", label: "S", color: "#ef4444" }, { id: "a", label: "A", color: "#22c55e" }], "board-stack": 8, "item-stack": 31,
}), font);
assert.deepEqual(tier.style.rows.map((row) => row.id), ["s", "a"]);
- assert.equal(tier.style.fonts[0]?.sources[0]?.artifact.digest, font.sources[0]!.artifact.digest);
+ assert.equal(tier.style.fonts[0]?.sources[0]?.artifact.resource, font.sources[0]!.artifact.resource);
assert.deepEqual([tier.style.boardStackingOrder, tier.style.itemStackingOrder], [8, 31]);
assert.throws(() => decodeTierBoardStyle(recipe("ranking.tier", { padding: 18 }), font), /does not accept padding/u);
assert.throws(() => decodeColumnStyle(recipe("ranking.column", { "tier-only": 1 }), font), /does not accept/u);
@@ -475,7 +475,7 @@ test("TopThree accepts one to three optional-image Items and removes active acce
const sound = (id: string): SynchronizedMedia => ({
timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 3 },
audio: {
- artifact: { kind: "blob", digest: fixtureDigest(`ranking-sound:${id}`), size: 128, mediaType: "audio/wav" },
+ artifact: { kind: "blob", resource: fixtureResource(`ranking-sound:${id}`), size: 128, mediaType: "audio/wav" },
},
});
diff --git a/packages/raster/src/program.ts b/packages/raster/src/program.ts
index 31c6a251..46722572 100644
--- a/packages/raster/src/program.ts
+++ b/packages/raster/src/program.ts
@@ -1,4 +1,4 @@
-import { canonicalize, isDigest } from "@hypit/protocol";
+import { canonicalize, isResourceId } from "@hypit/protocol";
import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
import type {
@@ -21,7 +21,7 @@ function color(value: string | undefined, subject: string, alpha = true): void {
assert(pattern.test(value), `${subject} must be ${alpha ? "#RRGGBB or #RRGGBBAA" : "#RRGGBBAA"}`);
}
function image(value: RasterLayer["source"], subject: string): void {
- assert(value.kind === "blob" && isDigest(value.digest) && Number.isSafeInteger(value.size)
+ assert(value.kind === "blob" && isResourceId(value.resource) && Number.isSafeInteger(value.size)
&& value.size >= 0 && value.mediaType.startsWith("image/"), `${subject} must be an image Blob Artifact`);
}
diff --git a/packages/raster/test/raster.test.ts b/packages/raster/test/raster.test.ts
index a8d12da0..b3efc0e8 100644
--- a/packages/raster/test/raster.test.ts
+++ b/packages/raster/test/raster.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
assertRasterRequest,
@@ -11,7 +11,7 @@ import {
rasterTransformRequest,
} from "@hypit/raster";
-const image = { kind: "blob" as const, digest: fixtureDigest("raster-image"), size: 12, mediaType: "image/png" };
+const image = { kind: "blob" as const, resource: fixtureResource("raster-image"), size: 12, mediaType: "image/png" };
test("one exact Raster capability carries both closed deterministic request variants", () => {
const transform = rasterTransformRequest(image, [{ kind: "encode", format: "webp", quality: 90 }]);
diff --git a/packages/reference-video-tools/src/authoring.ts b/packages/reference-video-tools/src/authoring.ts
index 9561cc9a..fefe8583 100644
--- a/packages/reference-video-tools/src/authoring.ts
+++ b/packages/reference-video-tools/src/authoring.ts
@@ -2,7 +2,6 @@ import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
import { existsSync } from "node:fs";
import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
import { createRequire } from "node:module";
import { cpus } from "node:os";
import { basename, dirname, join, resolve } from "node:path";
@@ -678,18 +677,18 @@ export async function stageAuthoringPreview(realized: Pick<RealizedAuthoringPrev
await mkdir(stage, { recursive: true });
const names = new Map<string, string>();
const mediaTypes = new Map<string, string>();
- for (const [digest, file] of realized.built.served) {
+ for (const [resource, file] of realized.built.served) {
const extension = file.mediaType === "text/css" ? ".css"
: file.mediaType === "application/javascript" || file.mediaType === "text/javascript" ? ".js"
: "";
- const name = `${digest.replace(/[^a-z0-9]/giu, "")}${extension}`;
+ const name = `${resource.replace(/[^a-z0-9]/giu, "")}${extension}`;
await writeFile(join(stage, name), file.bytes);
- names.set(digest, name);
+ names.set(resource, name);
mediaTypes.set(name, file.mediaType);
}
await writeFile(join(stage, "index.html"), materializeHyperframesHtml(document, (artifact) => {
- const name = names.get(artifact.digest);
- assert(name !== undefined, `the projection references Artifact ${artifact.digest}, which was not served`);
+ const name = names.get(artifact.resource);
+ assert(name !== undefined, `the projection references Artifact ${artifact.resource}, which was not served`);
return `./${name}`;
}), "utf8");
return { stage, document, mediaTypes };
@@ -731,7 +730,7 @@ export async function renderElement(input: RenderElementInput): Promise<Record<s
const {
runPath, built, previewMock, programFrames, frameOfToken, selections, segmentTokenCounts,
} = realized;
- const renderKey = createHash("sha256").update(`${resolve(runPath)}\u0000${input.reference_id ?? ""}`).digest("hex").slice(0, 12);
+ const renderKey = `${resolve(runPath)}:${input.reference_id ?? "default"}`;
const compareRoot = previewMock.root;
const canvas = built.canvas;
const frameRate = built.frameRate.numerator / built.frameRate.denominator;
diff --git a/packages/reference-video-tools/src/transcript.ts b/packages/reference-video-tools/src/transcript.ts
index b9418575..da254a32 100644
--- a/packages/reference-video-tools/src/transcript.ts
+++ b/packages/reference-video-tools/src/transcript.ts
@@ -1,6 +1,6 @@
import { access } from "node:fs/promises";
import { join } from "node:path";
-import { EndpointRegistry, MemoryArtifactStore } from "@hypit/driver-node";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
import type { Need } from "@hypit/protocol";
import { createLocalWhisperXProvider } from "@hypit/provider-whisperx-local";
import { sealSpeechEvidenceAudio } from "@hypit/speech";
@@ -75,8 +75,8 @@ export async function transcribeSpeechAudio(
language: WhisperXLanguage,
): Promise<readonly TranscriptPassage[]> {
const bytes = await readBytes(audioPath);
- const artifacts = new MemoryArtifactStore();
- const artifact = await artifacts.put(bytes, "audio/wav");
+ const resources = new MemoryResourceStore();
+ const artifact = await resources.put(bytes, "audio/wav");
const evidence = sealSpeechEvidenceAudio({ artifact, sampleFrames: sampleFrames(bytes) });
const need: Need = {
id: "need:reference-video-transcript",
@@ -93,7 +93,7 @@ export async function transcribeSpeechAudio(
const fulfillment = await resolved.registration.handler({
command: { kind: "fulfill-need", id: "command:reference-video-transcript", need },
need,
- artifacts,
+ resources,
credentials: {},
});
assert(fulfillment.value.kind === "inline", "WhisperX returned alignment evidence by reference");
diff --git a/packages/render-hyperframes/README.md b/packages/render-hyperframes/README.md
index 3b78ad62..5806bac3 100644
--- a/packages/render-hyperframes/README.md
+++ b/packages/render-hyperframes/README.md
@@ -4,9 +4,9 @@ Explicit author and capability boundary for final HyperFrames video rendering.
The package owns `<render:Video composition={...}/>` and lowers it to six ordinary Operations:
-1. compile the referenced `Composition` into a content-addressed `HyperframesDocument`;
+1. compile the referenced `Composition` into a `HyperframesDocument`;
2. request a silent, frame-exact `RenderedVisual`;
-3. compile every peer `AudioTrack` into one content-addressed `AudioProgramPlan`;
+3. compile every peer `AudioTrack` into one `AudioProgramPlan`;
4. request an exact 48 kHz `TimelineAudio`;
5. request one `MuxedMedia` from those two independently verified Products;
6. expose the verified mux Artifact unchanged as a domain-neutral `BlobArtifact`.
@@ -17,7 +17,7 @@ Provider for the exact visual capability. Media Providers independently realize
mux. None parses SVML or decides which Composition to render. Every result is bound to the same
ProgramSpace and exact frame/sample domain before it can become a final video Record.
-The output does not carry copied duration or lineage metadata. It is an ordinary content-addressed
+The output does not carry copied duration or lineage metadata. It is an ordinary Resource-backed
Blob and can therefore be connected directly to any later component that accepts Blob bytes. A
consumer that needs stream or duration facts must request explicit media inspection.
diff --git a/packages/render-hyperframes/test/render.test.ts b/packages/render-hyperframes/test/render.test.ts
index d5f9c7f8..7fc5ff2e 100644
--- a/packages/render-hyperframes/test/render.test.ts
+++ b/packages/render-hyperframes/test/render.test.ts
@@ -10,7 +10,7 @@ import { compositionDependency, compositionTypes, sealComposition } from "@hypit
import type { Composition } from "@hypit/composition";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import {
@@ -178,19 +178,19 @@ test("HyperFrames rendering is an explicit exact Need after ordinary document co
test("separate visual, audio and mux Endpoints complete one author-visible render", async () => {
const visualArtifact = {
kind: "blob" as const,
- digest: fixtureDigest("render-hyperframes:visual"),
+ resource: fixtureResource("render-hyperframes:visual"),
size: 12_345,
mediaType: "video/mp4",
};
const audioArtifact = {
kind: "blob" as const,
- digest: fixtureDigest("render-hyperframes:audio"),
+ resource: fixtureResource("render-hyperframes:audio"),
size: 4_096,
mediaType: "audio/wav",
};
const finalArtifact = {
kind: "blob" as const,
- digest: fixtureDigest("render-hyperframes:final-video"),
+ resource: fixtureResource("render-hyperframes:final-video"),
size: 16_441,
mediaType: "video/mp4",
};
@@ -254,7 +254,7 @@ test("separate visual, audio and mux Endpoints complete one author-visible rende
record.type.module.name === artifactTypes.blob.module.name
&& record.type.name === artifactTypes.blob.name
&& record.value.kind === "blob"
- && record.value.digest === finalArtifact.digest);
+ && record.value.resource === finalArtifact.resource);
assert(video, "missing final BlobArtifact");
assert.deepEqual(video.value, finalArtifact);
});
@@ -273,7 +273,7 @@ test("a render Product with another frame domain is rejected by the explicit dow
canvas: document.canvas,
artifact: {
kind: "blob",
- digest: fixtureDigest("render-hyperframes:wrong-domain"),
+ resource: fixtureResource("render-hyperframes:wrong-domain"),
size: 1,
mediaType: "video/mp4",
},
@@ -290,7 +290,7 @@ test("a render Product with another frame domain is rejected by the explicit dow
value: stored(sealTimelineAudio({
artifact: {
kind: "blob",
- digest: fixtureDigest("render-hyperframes:domain-check-audio"),
+ resource: fixtureResource("render-hyperframes:domain-check-audio"),
size: 1,
mediaType: "audio/wav",
},
@@ -309,7 +309,7 @@ test("a render Product with another frame domain is rejected by the explicit dow
});
const fixtureModule = { name: "example.composition-fixture", version: "1" } as const;
-const fixtureSurfaceDigest = fixtureDigest("example.composition-fixture/surface@1");
+const fixtureSurfaceDigest = fixtureResource("example.composition-fixture/surface@1");
const fixtureSurface = {
name: "composition", tag: "Composition", mode: "structured",
outputs: [compositionTypes.composition, semanticTrackTypes.track],
diff --git a/packages/artifact-store-fs/README.md b/packages/resource-store-fs/README.md
similarity index 86%
rename from packages/artifact-store-fs/README.md
rename to packages/resource-store-fs/README.md
index 961ae25e..02a88ac7 100644
--- a/packages/artifact-store-fs/README.md
+++ b/packages/resource-store-fs/README.md
@@ -1,8 +1,8 @@
-# `@hypit/artifact-store-fs`
+# `@hypit/resource-store-fs`
Filesystem implementation of the Runtime's transient byte port. The local Runtime gives each Build
its own working directory and removes it after the project Build Result has accepted the public
Outputs.
The Runtime Profile does not select this package or its path. It stores no Build Result, credentials
-or author source. Code embedding the Runtime directly may still construct `FileArtifactStore`.
+or author source. Code embedding the Runtime directly may still construct `FileResourceStore`.
diff --git a/packages/artifact-store-fs/package.json b/packages/resource-store-fs/package.json
similarity index 86%
rename from packages/artifact-store-fs/package.json
rename to packages/resource-store-fs/package.json
index d6983948..47d9c80a 100644
--- a/packages/artifact-store-fs/package.json
+++ b/packages/resource-store-fs/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/artifact-store-fs",
+ "name": "@hypit/resource-store-fs",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
diff --git a/packages/resource-store-fs/src/index.ts b/packages/resource-store-fs/src/index.ts
new file mode 100644
index 00000000..2b6aeac5
--- /dev/null
+++ b/packages/resource-store-fs/src/index.ts
@@ -0,0 +1,2 @@
+export { FileResourceStore } from "./store.js";
+export type * from "./store.js";
diff --git a/packages/resource-store-fs/src/store.ts b/packages/resource-store-fs/src/store.ts
new file mode 100644
index 00000000..75ab7f06
--- /dev/null
+++ b/packages/resource-store-fs/src/store.ts
@@ -0,0 +1,149 @@
+import { randomUUID } from "node:crypto";
+import {
+ link,
+ mkdir,
+ open as openFile,
+ rm,
+ stat,
+} from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { isResourceId } from "@hypit/protocol";
+import type { BlobRef, ResourceId } from "@hypit/protocol";
+import type { ResourceStore } from "@hypit/runtime";
+
+function resourcePath(root: string, resource: ResourceId): string {
+ if (!isResourceId(resource)) throw new Error("Resource id is invalid");
+ return join(root, "resources", resource);
+}
+
+function isNodeError(error: unknown, code: string): boolean {
+ return error instanceof Error && "code" in error && error.code === code;
+}
+
+/** Build-local files keyed by opaque resource instance identity. */
+export class FileResourceStore implements ResourceStore {
+ readonly root: string;
+
+ constructor(root: string) {
+ if (root.trim().length === 0) throw new Error("Resource root must not be empty");
+ this.root = resolve(root);
+ }
+
+ async #store(
+ resource: ResourceId,
+ chunks: AsyncIterable<Uint8Array>,
+ expectedSize?: number,
+ ): Promise<number> {
+ const incoming = join(this.root, ".incoming");
+ await mkdir(incoming, { recursive: true });
+ const temporary = join(incoming, `res_${randomUUID()}`);
+ const handle = await openFile(temporary, "wx");
+ let size = 0;
+ try {
+ try {
+ for await (const value of chunks) {
+ if (!(value instanceof Uint8Array)) throw new Error("Resource stream yielded non-bytes");
+ const chunk = Uint8Array.from(value);
+ size += chunk.byteLength;
+ if (!Number.isSafeInteger(size)) throw new Error("Resource stream exceeds the supported size");
+ let offset = 0;
+ while (offset < chunk.byteLength) {
+ const written = await handle.write(chunk, offset, chunk.byteLength - offset);
+ offset += written.bytesWritten;
+ }
+ }
+ } finally {
+ await handle.close();
+ }
+ if (expectedSize !== undefined && size !== expectedSize) {
+ throw new Error(`Resource ${resource} has size ${size}, expected ${expectedSize}`);
+ }
+ const path = resourcePath(this.root, resource);
+ await mkdir(join(this.root, "resources"), { recursive: true });
+ try {
+ await link(temporary, path);
+ } catch (error) {
+ if (!isNodeError(error, "EEXIST")) throw error;
+ }
+ return size;
+ } finally {
+ await rm(temporary, { force: true });
+ }
+ }
+
+ async put(bytes: Uint8Array, mediaType: string): Promise<BlobRef> {
+ const copy = Uint8Array.from(bytes);
+ return await this.putStream((async function* () { yield copy; })(), mediaType);
+ }
+
+ async putStream(chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<BlobRef> {
+ if (mediaType.trim().length === 0) throw new Error("Resource mediaType must not be empty");
+ const resource = `res_${randomUUID()}` as ResourceId;
+ const size = await this.#store(resource, chunks);
+ return { kind: "blob", resource, size, mediaType };
+ }
+
+ async write(resource: BlobRef, bytes: Uint8Array): Promise<void> {
+ const copy = Uint8Array.from(bytes);
+ await this.writeStream(resource, (async function* () { yield copy; })());
+ }
+
+ async writeStream(resource: BlobRef, chunks: AsyncIterable<Uint8Array>): Promise<void> {
+ if (!isResourceId(resource.resource)) throw new Error("Resource id is invalid");
+ if (resource.mediaType.trim().length === 0) throw new Error("Resource mediaType must not be empty");
+ await this.#store(resource.resource, chunks, resource.size);
+ }
+
+ async get(resource: ResourceId): Promise<Uint8Array | undefined> {
+ const stream = await this.open(resource);
+ if (stream === undefined) return undefined;
+ const chunks: Uint8Array[] = [];
+ let size = 0;
+ for await (const chunk of stream) {
+ chunks.push(chunk);
+ size += chunk.byteLength;
+ }
+ const bytes = new Uint8Array(size);
+ let offset = 0;
+ for (const chunk of chunks) {
+ bytes.set(chunk, offset);
+ offset += chunk.byteLength;
+ }
+ return bytes;
+ }
+
+ async open(resource: ResourceId): Promise<AsyncIterable<Uint8Array> | undefined> {
+ const path = resourcePath(this.root, resource);
+ try {
+ if (!(await stat(path)).isFile()) throw new Error(`Resource ${resource} is not a file`);
+ } catch (error) {
+ if (isNodeError(error, "ENOENT")) return undefined;
+ throw error;
+ }
+ return (async function* () {
+ const handle = await openFile(path, "r");
+ try {
+ const buffer = new Uint8Array(1024 * 1024);
+ let position = 0;
+ while (true) {
+ const result = await handle.read(buffer, 0, buffer.byteLength, position);
+ if (result.bytesRead === 0) break;
+ position += result.bytesRead;
+ yield buffer.slice(0, result.bytesRead);
+ }
+ } finally {
+ await handle.close();
+ }
+ })();
+ }
+
+ async has(resource: ResourceId): Promise<boolean> {
+ try {
+ return (await stat(resourcePath(this.root, resource))).isFile();
+ } catch (error) {
+ if (isNodeError(error, "ENOENT")) return false;
+ throw error;
+ }
+ }
+}
diff --git a/packages/artifact-store-fs/test/store.test.ts b/packages/resource-store-fs/test/store.test.ts
similarity index 59%
rename from packages/artifact-store-fs/test/store.test.ts
rename to packages/resource-store-fs/test/store.test.ts
index 9be80a2e..7983f70e 100644
--- a/packages/artifact-store-fs/test/store.test.ts
+++ b/packages/resource-store-fs/test/store.test.ts
@@ -4,36 +4,36 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
-import { FileArtifactStore } from "@hypit/artifact-store-fs";
+import { FileResourceStore } from "@hypit/resource-store-fs";
-test("filesystem artifacts are content-addressed and survive adapter restart", async () => {
- const directory = await mkdtemp(join(tmpdir(), "hypit-artifacts-"));
+test("filesystem resources are independent and survive adapter restart", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "hypit-resources-"));
try {
const bytes = new TextEncoder().encode("one immutable video artifact");
- const first = new FileArtifactStore(directory);
+ const first = new FileResourceStore(directory);
const left = await first.put(bytes, "video/mp4");
const right = await first.put(bytes, "video/mp4");
- assert.equal(left.digest, right.digest);
+ assert.notEqual(left.resource, right.resource);
assert.equal(left.size, bytes.byteLength);
- const reopened = new FileArtifactStore(directory);
- assert.equal(await reopened.has(left.digest), true);
- assert.deepEqual(await reopened.get(left.digest), bytes);
+ const reopened = new FileResourceStore(directory);
+ assert.equal(await reopened.has(left.resource), true);
+ assert.deepEqual(await reopened.get(left.resource), bytes);
} finally {
await rm(directory, { recursive: true, force: true });
}
});
-test("filesystem artifacts stream writes and reads", async () => {
- const directory = await mkdtemp(join(tmpdir(), "hypit-artifacts-stream-"));
+test("filesystem resources stream writes and reads", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "hypit-resources-stream-"));
try {
- const store = new FileArtifactStore(directory);
+ const store = new FileResourceStore(directory);
const artifact = await store.putStream((async function* () {
yield new TextEncoder().encode("streamed ");
yield new TextEncoder().encode("artifact");
})(), "application/octet-stream");
- const opened = await store.open(artifact.digest);
+ const opened = await store.open(artifact.resource);
assert.notEqual(opened, undefined);
const values: number[] = [];
for await (const chunk of opened!) values.push(...chunk);
diff --git a/packages/artifact-store-s3/README.md b/packages/resource-store-s3/README.md
similarity index 94%
rename from packages/artifact-store-s3/README.md
rename to packages/resource-store-s3/README.md
index c50c7fab..c462cfb7 100644
--- a/packages/artifact-store-s3/README.md
+++ b/packages/resource-store-s3/README.md
@@ -1,4 +1,4 @@
-# `@hypit/artifact-store-s3`
+# `@hypit/resource-store-s3`
S3 implementation of the Runtime's internal byte port. It is a library for a Runtime implementation
that deliberately embeds it; the local Runtime does not expose it as a Runtime Profile choice.
diff --git a/packages/artifact-store-s3/package.json b/packages/resource-store-s3/package.json
similarity index 88%
rename from packages/artifact-store-s3/package.json
rename to packages/resource-store-s3/package.json
index 638c8dca..d0487722 100644
--- a/packages/artifact-store-s3/package.json
+++ b/packages/resource-store-s3/package.json
@@ -1,5 +1,5 @@
{
- "name": "@hypit/artifact-store-s3",
+ "name": "@hypit/resource-store-s3",
"version": "0.0.0-dev",
"license": "SEE LICENSE IN LICENSE",
"private": true,
diff --git a/packages/artifact-store-s3/src/client.ts b/packages/resource-store-s3/src/client.ts
similarity index 91%
rename from packages/artifact-store-s3/src/client.ts
rename to packages/resource-store-s3/src/client.ts
index 0de355a8..d0b0fae1 100644
--- a/packages/artifact-store-s3/src/client.ts
+++ b/packages/resource-store-s3/src/client.ts
@@ -1,9 +1,7 @@
import {
AbortMultipartUploadCommand,
CompleteMultipartUploadCommand,
- CopyObjectCommand,
CreateMultipartUploadCommand,
- DeleteObjectCommand,
GetObjectCommand,
HeadObjectCommand,
PutObjectCommand,
@@ -13,9 +11,7 @@ import {
import type {
AbortMultipartUploadCommandInput,
CompleteMultipartUploadCommandInput,
- CopyObjectCommandInput,
CreateMultipartUploadCommandInput,
- DeleteObjectCommandInput,
GetObjectCommandInput,
PutObjectCommandInput,
S3ClientConfig,
@@ -24,7 +20,7 @@ import type {
/**
* `put` and `get` are the whole port. The rest are optional: a client that
- * omits them leaves the store implementing only the three-method ArtifactStore,
+ * omits them leaves the store implementing only the three-method ResourceStore,
* which is exactly what the optional Streaming facet means.
*/
export type S3ObjectClient = {
@@ -42,8 +38,6 @@ export type S3ObjectClient = {
uploadPart?(input: UploadPartCommandInput): Promise<{ readonly etag: string }>;
completeMultipart?(input: CompleteMultipartUploadCommandInput): Promise<void>;
abortMultipart?(input: AbortMultipartUploadCommandInput): Promise<void>;
- copy?(input: CopyObjectCommandInput): Promise<void>;
- delete?(input: DeleteObjectCommandInput): Promise<void>;
};
function statusCode(error: unknown): number | undefined {
@@ -133,12 +127,4 @@ export class AwsS3ObjectClient implements S3ObjectClient {
await this.#client.send(new AbortMultipartUploadCommand(input));
}
- async copy(input: CopyObjectCommandInput): Promise<void> {
- await this.#client.send(new CopyObjectCommand(input));
- }
-
- async delete(input: DeleteObjectCommandInput): Promise<void> {
- await this.#client.send(new DeleteObjectCommand(input));
- }
-
}
diff --git a/packages/resource-store-s3/src/index.ts b/packages/resource-store-s3/src/index.ts
new file mode 100644
index 00000000..48e1d513
--- /dev/null
+++ b/packages/resource-store-s3/src/index.ts
@@ -0,0 +1,10 @@
+export { AwsS3ObjectClient } from "./client.js";
+export type { S3ObjectClient } from "./client.js";
+export {
+ S3ResourceStore,
+ createS3ResourceStore,
+ normalizeS3ResourcePrefix,
+ s3ResourceKey,
+ s3ResourceStoreModuleRef,
+} from "./store.js";
+export type * from "./store.js";
diff --git a/packages/resource-store-s3/src/store.ts b/packages/resource-store-s3/src/store.ts
new file mode 100644
index 00000000..7d682e7d
--- /dev/null
+++ b/packages/resource-store-s3/src/store.ts
@@ -0,0 +1,244 @@
+import { randomUUID } from "node:crypto";
+
+import { isResourceId } from "@hypit/protocol";
+import type { BlobRef, ResourceId } from "@hypit/protocol";
+import type { ResourceStore } from "@hypit/runtime";
+
+import { AwsS3ObjectClient } from "./client.js";
+import type { S3ObjectClient } from "./client.js";
+
+export const s3ResourceStoreModuleRef = {
+ name: "@hypit/resource-store-s3",
+ version: "1",
+} as const;
+
+export function normalizeS3ResourcePrefix(prefix: string | undefined): string {
+ if (prefix === undefined || prefix.length === 0) return "";
+ const normalized = prefix.replace(/^\/+|\/+$/gu, "");
+ assert(normalized.length > 0, "S3 Resource prefix must contain a non-slash character");
+ assert(!normalized.split("/").some((part) => part === "." || part === ".."),
+ "S3 Resource prefix cannot contain dot path segments");
+ return normalized;
+}
+
+export function s3ResourceKey(prefix: string | undefined, resource: ResourceId): string {
+ if (!isResourceId(resource)) throw new Error("Resource id is invalid");
+ const normalized = normalizeS3ResourcePrefix(prefix);
+ const relative = `resources/${resource}`;
+ return normalized.length === 0 ? relative : `${normalized}/${relative}`;
+}
+
+type S3Location = {
+ readonly bucket: string;
+ readonly prefix?: string;
+ readonly expectedBucketOwner?: string;
+};
+
+export type S3ResourceStoreOptions = S3Location & {
+ readonly client: S3ObjectClient;
+ readonly partSizeBytes?: number;
+};
+
+export type CreateS3ResourceStorePackageOptions = S3Location & {
+ readonly instance?: string;
+ readonly partSizeBytes?: number;
+ readonly region?: string;
+ readonly endpoint?: string;
+ readonly forcePathStyle?: boolean;
+ readonly client?: S3ObjectClient;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function positiveInteger(value: number, subject: string): number {
+ assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive safe integer`);
+ return value;
+}
+
+/** Optional S3 byte store for Runtime implementations that deliberately embed it. */
+export class S3ResourceStore implements ResourceStore {
+ readonly #client: S3ObjectClient;
+ readonly #bucket: string;
+ readonly #prefix: string;
+ readonly #expectedBucketOwner: string | undefined;
+ readonly #partSizeBytes: number;
+ readonly open?: (resource: ResourceId) => Promise<AsyncIterable<Uint8Array> | undefined>;
+ readonly putStream?: (chunks: AsyncIterable<Uint8Array>, mediaType: string) => Promise<BlobRef>;
+ readonly writeStream?: (resource: BlobRef, chunks: AsyncIterable<Uint8Array>) => Promise<void>;
+
+ constructor(options: S3ResourceStoreOptions) {
+ assert(options.bucket.trim().length > 0, "S3 Resource bucket must not be empty");
+ if (options.expectedBucketOwner !== undefined) {
+ assert(options.expectedBucketOwner.trim().length > 0, "expected S3 bucket owner must not be empty");
+ }
+ this.#client = options.client;
+ this.#bucket = options.bucket;
+ this.#prefix = normalizeS3ResourcePrefix(options.prefix);
+ this.#expectedBucketOwner = options.expectedBucketOwner;
+ this.#partSizeBytes = positiveInteger(options.partSizeBytes ?? 16 * 1024 * 1024, "partSizeBytes");
+ assert(this.#partSizeBytes >= 5 * 1024 * 1024, "S3 requires multipart parts of at least 5 MiB");
+ const client = options.client;
+ if (client.open !== undefined && client.createMultipart !== undefined && client.uploadPart !== undefined
+ && client.completeMultipart !== undefined) {
+ this.open = (resource) => this.#openStream(resource);
+ this.putStream = (chunks, mediaType) => this.#putStream(chunks, mediaType);
+ this.writeStream = async (resource, chunks) => {
+ await this.#storeStream(resource.resource, chunks, resource.mediaType, resource.size);
+ };
+ }
+ }
+
+ key(resource: ResourceId): string {
+ return s3ResourceKey(this.#prefix, resource);
+ }
+
+ #owner(): { readonly ExpectedBucketOwner?: string } {
+ return this.#expectedBucketOwner === undefined ? {} : { ExpectedBucketOwner: this.#expectedBucketOwner };
+ }
+
+ async put(bytes: Uint8Array, mediaType: string): Promise<BlobRef> {
+ assert(mediaType.trim().length > 0, "Resource mediaType must not be empty");
+ const copy = Uint8Array.from(bytes);
+ const resource = `res_${randomUUID()}` as ResourceId;
+ await this.#client.put({
+ Bucket: this.#bucket,
+ Key: this.key(resource),
+ Body: copy,
+ ContentLength: copy.byteLength,
+ ContentType: mediaType,
+ ...this.#owner(),
+ });
+ return { kind: "blob", resource, size: copy.byteLength, mediaType };
+ }
+
+ async write(resource: BlobRef, bytes: Uint8Array): Promise<void> {
+ const copy = Uint8Array.from(bytes);
+ assert(copy.byteLength === resource.size,
+ `Resource ${resource.resource} has size ${copy.byteLength}, expected ${resource.size}`);
+ await this.#client.put({
+ Bucket: this.#bucket,
+ Key: this.key(resource.resource),
+ Body: copy,
+ ContentLength: copy.byteLength,
+ ContentType: resource.mediaType,
+ ...this.#owner(),
+ });
+ }
+
+ async get(resource: ResourceId): Promise<Uint8Array | undefined> {
+ const bytes = await this.#client.get({
+ Bucket: this.#bucket,
+ Key: this.key(resource),
+ ...this.#owner(),
+ });
+ return bytes === undefined ? undefined : Uint8Array.from(bytes);
+ }
+
+ async has(resource: ResourceId): Promise<boolean> {
+ if (this.#client.head === undefined) {
+ return await this.#client.get({ Bucket: this.#bucket, Key: this.key(resource), ...this.#owner() }) !== undefined;
+ }
+ return await this.#client.head({ Bucket: this.#bucket, Key: this.key(resource), ...this.#owner() }) !== undefined;
+ }
+
+ async #openStream(resource: ResourceId): Promise<AsyncIterable<Uint8Array> | undefined> {
+ return await this.#client.open!({
+ Bucket: this.#bucket,
+ Key: this.key(resource),
+ ...this.#owner(),
+ });
+ }
+
+ async #putStream(chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<BlobRef> {
+ assert(mediaType.trim().length > 0, "Resource mediaType must not be empty");
+ const resource = `res_${randomUUID()}` as ResourceId;
+ const size = await this.#storeStream(resource, chunks, mediaType);
+ return { kind: "blob", resource, size, mediaType };
+ }
+
+ async #storeStream(
+ resource: ResourceId,
+ chunks: AsyncIterable<Uint8Array>,
+ mediaType: string,
+ expectedSize?: number,
+ ): Promise<number> {
+ const client = this.#client as Required<Pick<S3ObjectClient,
+ "createMultipart" | "uploadPart" | "completeMultipart">> & S3ObjectClient;
+ const key = this.key(resource);
+ const owner = this.#owner();
+ const uploadId = await client.createMultipart({
+ Bucket: this.#bucket, Key: key, ContentType: mediaType, ...owner,
+ });
+ const parts: { PartNumber: number; ETag: string }[] = [];
+ let pending: Uint8Array[] = [];
+ let pendingBytes = 0;
+ let size = 0;
+ const flush = async (): Promise<void> => {
+ if (pendingBytes === 0 && parts.length > 0) return;
+ const body = new Uint8Array(pendingBytes);
+ let offset = 0;
+ for (const piece of pending) {
+ body.set(piece, offset);
+ offset += piece.byteLength;
+ }
+ pending = [];
+ pendingBytes = 0;
+ const partNumber = parts.length + 1;
+ const { etag } = await client.uploadPart({
+ Bucket: this.#bucket, Key: key, UploadId: uploadId,
+ PartNumber: partNumber, Body: body, ContentLength: body.byteLength, ...owner,
+ });
+ parts.push({ PartNumber: partNumber, ETag: etag });
+ };
+ try {
+ for await (const value of chunks) {
+ if (!(value instanceof Uint8Array)) throw new Error("Resource stream yielded non-bytes");
+ const chunk = Uint8Array.from(value);
+ size += chunk.byteLength;
+ if (!Number.isSafeInteger(size)) throw new Error("Resource stream exceeds the supported size");
+ let offset = 0;
+ while (offset < chunk.byteLength) {
+ const take = Math.min(this.#partSizeBytes - pendingBytes, chunk.byteLength - offset);
+ pending.push(chunk.slice(offset, offset + take));
+ pendingBytes += take;
+ offset += take;
+ if (pendingBytes === this.#partSizeBytes) await flush();
+ }
+ }
+ if (pendingBytes > 0 || parts.length === 0) await flush();
+ if (expectedSize !== undefined && size !== expectedSize) {
+ throw new Error(`Resource ${resource} has size ${size}, expected ${expectedSize}`);
+ }
+ await client.completeMultipart({
+ Bucket: this.#bucket, Key: key, UploadId: uploadId,
+ MultipartUpload: { Parts: parts }, ...owner,
+ });
+ return size;
+ } catch (error) {
+ await client.abortMultipart?.({
+ Bucket: this.#bucket, Key: key, UploadId: uploadId, ...owner,
+ }).catch(() => undefined);
+ throw error;
+ }
+ }
+}
+
+export function createS3ResourceStore(
+ options: CreateS3ResourceStorePackageOptions,
+): S3ResourceStore {
+ const prefix = normalizeS3ResourcePrefix(options.prefix);
+ const client = options.client ?? new AwsS3ObjectClient({
+ ...(options.region === undefined ? {} : { region: options.region }),
+ ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
+ ...(options.forcePathStyle === undefined ? {} : { forcePathStyle: options.forcePathStyle }),
+ });
+ return new S3ResourceStore({
+ client,
+ bucket: options.bucket,
+ ...(options.partSizeBytes === undefined ? {} : { partSizeBytes: options.partSizeBytes }),
+ ...(prefix.length === 0 ? {} : { prefix }),
+ ...(options.expectedBucketOwner === undefined ? {} : { expectedBucketOwner: options.expectedBucketOwner }),
+ });
+}
diff --git a/packages/artifact-store-s3/test/store.test.ts b/packages/resource-store-s3/test/store.test.ts
similarity index 65%
rename from packages/artifact-store-s3/test/store.test.ts
rename to packages/resource-store-s3/test/store.test.ts
index d7d1de99..160e46e8 100644
--- a/packages/artifact-store-s3/test/store.test.ts
+++ b/packages/resource-store-s3/test/store.test.ts
@@ -1,9 +1,9 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { S3ArtifactStore } from "@hypit/artifact-store-s3";
-import type { S3ObjectClient } from "@hypit/artifact-store-s3";
-import { isStreamingArtifactStore } from "@hypit/runtime";
+import { S3ResourceStore } from "@hypit/resource-store-s3";
+import type { S3ObjectClient } from "@hypit/resource-store-s3";
+import { isStreamingResourceStore } from "@hypit/runtime";
class FakeS3 implements S3ObjectClient {
readonly values = new Map<string, Uint8Array>();
@@ -22,15 +22,15 @@ class FakeS3 implements S3ObjectClient {
}
}
-test("S3 artifacts use deterministic content-addressed keys", async () => {
+test("S3 resources use independent execution-local keys", async () => {
const client = new FakeS3();
- const store = new S3ArtifactStore({ client, bucket: "fixture", prefix: "projects/acme" });
+ const store = new S3ResourceStore({ client, bucket: "fixture", prefix: "projects/acme" });
const bytes = new TextEncoder().encode("one immutable remote artifact");
const first = await store.put(bytes, "video/mp4");
const second = await store.put(bytes, "video/mp4");
- assert.equal(first.digest, second.digest);
- assert.match(store.key(first.digest), /^projects\/acme\/sha256\//u);
- assert.deepEqual(await store.get(first.digest), bytes);
+ assert.notEqual(first.resource, second.resource);
+ assert.match(store.key(first.resource), /^projects\/acme\/resources\/res_/u);
+ assert.deepEqual(await store.get(first.resource), bytes);
});
/** A client that can do everything, backed by an in-memory bucket. */
@@ -81,64 +81,51 @@ class FullFakeS3 extends FakeS3 {
async abortMultipart() {}
- async copy(input: Parameters<NonNullable<S3ObjectClient["copy"]>>[0]) {
- const source = input.CopySource!.slice(input.CopySource!.indexOf("/") + 1);
- const value = this.values.get(source);
- if (value === undefined) throw new Error(`copy source ${source} is absent`);
- this.values.set(input.Key!, Uint8Array.from(value));
- }
-
- async delete(input: Parameters<NonNullable<S3ObjectClient["delete"]>>[0]) {
- this.values.delete(input.Key!);
- }
-
}
test("streaming is exposed only when the client supports it", () => {
- const store = new S3ArtifactStore({ client: new FakeS3(), bucket: "fixture" });
- assert.equal(isStreamingArtifactStore(store), false);
- const full = new S3ArtifactStore({ client: new FullFakeS3(), bucket: "fixture" });
- assert.equal(isStreamingArtifactStore(full), true);
+ const store = new S3ResourceStore({ client: new FakeS3(), bucket: "fixture" });
+ assert.equal(isStreamingResourceStore(store), false);
+ const full = new S3ResourceStore({ client: new FullFakeS3(), bucket: "fixture" });
+ assert.equal(isStreamingResourceStore(full), true);
});
-test("a streamed Artifact reaches the content-addressed key it earned by being hashed", async () => {
+test("a streamed Resource reaches its declared resource key", async () => {
const client = new FullFakeS3();
- const store = new S3ArtifactStore({ client, bucket: "fixture", prefix: "svml" });
+ const store = new S3ResourceStore({ client, bucket: "fixture", prefix: "svml" });
const parts = ["first ", "second ", "third"].map((text) => new TextEncoder().encode(text));
const ref = await store.putStream!((async function* () { yield* parts; })(), "video/mp4");
const whole = new TextEncoder().encode("first second third");
assert.equal(ref.size, whole.byteLength);
- assert.deepEqual(await store.get(ref.digest), whole);
- assert.match(store.key(ref.digest), /^svml\/sha256\//u);
- // The staging key is gone, so it is not mistaken for an Artifact.
- assert.deepEqual([...client.values.keys()].filter((key) => key.includes(".incoming")), []);
+ assert.deepEqual(await store.get(ref.resource), whole);
+ assert.match(store.key(ref.resource), /^svml\/resources\/res_/u);
});
-test("an empty Artifact is a legitimate one, and S3 will not accept a partless upload", async () => {
- const store = new S3ArtifactStore({ client: new FullFakeS3(), bucket: "fixture" });
+test("an empty Resource is legitimate even though S3 will not accept a partless upload", async () => {
+ const store = new S3ResourceStore({ client: new FullFakeS3(), bucket: "fixture" });
const ref = await store.putStream!((async function* () {})(), "application/octet-stream");
assert.equal(ref.size, 0);
- assert.deepEqual(await store.get(ref.digest), new Uint8Array(0));
+ assert.deepEqual(await store.get(ref.resource), new Uint8Array(0));
});
test("a streamed read hands back bytes as they arrive", async () => {
const client = new FullFakeS3();
- const store = new S3ArtifactStore({ client, bucket: "fixture" });
+ const store = new S3ResourceStore({ client, bucket: "fixture" });
const bytes = new TextEncoder().encode("streamed artifact bytes");
const ref = await store.put(bytes, "text/plain");
const chunks: Uint8Array[] = [];
- for await (const chunk of (await store.open!(ref.digest))!) chunks.push(chunk);
+ for await (const chunk of (await store.open!(ref.resource))!) chunks.push(chunk);
assert.equal(chunks.length, 2, "the stream was not assembled on the caller's behalf");
});
test("presence uses object metadata without downloading bytes", async () => {
const client = new FullFakeS3();
- const store = new S3ArtifactStore({ client, bucket: "fixture" });
+ const store = new S3ResourceStore({ client, bucket: "fixture" });
const ref = await store.put(new TextEncoder().encode("present"), "text/plain");
const gets = client.gets;
- assert.equal(await store.has(ref.digest), true);
+ assert.equal(await store.has(ref.resource), true);
assert.equal(client.heads, 1);
assert.equal(client.gets, gets, "has did not download the object");
});
diff --git a/packages/run-markup/README.md b/packages/run-markup/README.md
index 131a18c9..44721bc5 100644
--- a/packages/run-markup/README.md
+++ b/packages/run-markup/README.md
@@ -18,7 +18,7 @@ One Run Source is self-described and names one Author Source explicitly:
The Author Source's own Header—not this file and not its suffix—selects its Author Frontend.
-`<value>` declares a typed zero-input `StoredValue`. `<file>` content-addresses ordinary source
+`<value>` declares a typed zero-input `StoredValue`. `<file>` admits ordinary source
bytes as the explicitly named blob Type; Run itself does not assume an Artifact module.
`<build-record>` exposes a verified prior Build Record as a zero-input Candidate. `<fragment>`
instantiates a trusted package Fragment and may
diff --git a/packages/run-markup/test/run.test.ts b/packages/run-markup/test/run.test.ts
index 61c18a4e..dcdfb49a 100644
--- a/packages/run-markup/test/run.test.ts
+++ b/packages/run-markup/test/run.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
createResolvedClosure,
@@ -204,7 +204,7 @@ test("a source file is an ordinary BlobArtifact Candidate", async () => {
readFile(from, mediaType) {
assert.equal(from, "./approved.mp4");
assert.equal(mediaType, "video/mp4");
- return { kind: "blob", digest: fixtureDigest("approved video"), size: 14, mediaType };
+ return { kind: "blob", resource: fixtureResource("approved video"), size: 14, mediaType };
},
resolveBuildRecord() { throw new Error("not used"); },
});
diff --git a/packages/run/src/resolve.ts b/packages/run/src/resolve.ts
index 9baf8c51..00d603ad 100644
--- a/packages/run/src/resolve.ts
+++ b/packages/run/src/resolve.ts
@@ -75,7 +75,7 @@ function assertStoredValue(value: unknown, subject: string): asserts value is St
const item = value as Record<string, unknown>;
if (item.kind === "inline" && Object.hasOwn(item, "value")) return;
if (item.kind === "blob"
- && typeof item.digest === "string"
+ && typeof item.resource === "string"
&& Number.isSafeInteger(item.size)
&& typeof item.mediaType === "string") return;
throw new Error(`${subject} is not an inline or blob StoredValue`);
diff --git a/packages/run/src/types.ts b/packages/run/src/types.ts
index 50688faf..aa5ced2a 100644
--- a/packages/run/src/types.ts
+++ b/packages/run/src/types.ts
@@ -38,7 +38,7 @@ export type RunProvidedValue = {
readonly from: string;
};
-/** Ordinary source file admitted as one content-addressed Candidate of an explicitly named blob Type. */
+/** Ordinary source file admitted as one Resource Candidate of an explicitly named blob Type. */
export type RunProvidedFile = {
readonly kind: "file";
readonly id: string;
diff --git a/packages/runtime-host-node/src/index.ts b/packages/runtime-host-node/src/index.ts
index e1a42a18..cb620f1b 100644
--- a/packages/runtime-host-node/src/index.ts
+++ b/packages/runtime-host-node/src/index.ts
@@ -6,7 +6,7 @@ import type { ArtifactAttachment } from "@hypit/workspace";
import type { BuildResultReuse } from "@hypit/build-result";
import type { BuildResultRepository } from "@hypit/build-result";
import type { BuildResultRepositoryLocation } from "@hypit/build-result-kit";
-import type { BuildDefinition, BuildState, CapabilityRef, Digest } from "@hypit/protocol";
+import type { BuildDefinition, BuildState, CapabilityRef, ResourceId } from "@hypit/protocol";
import type {
BuildCatalogDescriptor,
BuildCatalogEntry,
@@ -59,9 +59,9 @@ export type RuntimeHostArchive = {
close(): void | Promise<void>;
};
-export type RuntimeHostArtifactAccess = {
- readArtifact(digest: Digest): Promise<Uint8Array | undefined>;
- openArtifact(digest: Digest): Promise<AsyncIterable<Uint8Array> | undefined>;
+export type RuntimeHostResourceAccess = {
+ readResource(resource: ResourceId): Promise<Uint8Array | undefined>;
+ openResource(resource: ResourceId): Promise<AsyncIterable<Uint8Array> | undefined>;
close(): void | Promise<void>;
};
@@ -75,7 +75,7 @@ export type RuntimeHostCredentialControl = {
close(): void | Promise<void>;
};
-export type RuntimeHostExecution = RuntimeHostArchive & RuntimeHostArtifactAccess & RuntimeHostCredentialControl & {
+export type RuntimeHostExecution = RuntimeHostArchive & RuntimeHostResourceAccess & RuntimeHostCredentialControl & {
build(request: {
readonly id: string;
readonly definition: BuildDefinition;
@@ -164,7 +164,7 @@ export type NodeRuntimeHost = {
}): Promise<RuntimeController>;
createRuntime(): Promise<RuntimeHostExecution>;
openArchive(options?: { readonly readOnly?: boolean }): Promise<RuntimeHostArchive>;
- openArtifacts(): Promise<RuntimeHostArtifactAccess>;
+ openResources(): Promise<RuntimeHostResourceAccess>;
openCredentials(endpoint: string): Promise<RuntimeHostCredentialControl>;
/** Open the project Repository selected by this Profile, or the supplied zero-config file default. */
openResults?(defaultRoot: string): Promise<{
diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.md
index 9b3300a2..b63f94d8 100644
--- a/packages/runtime-local/README.md
+++ b/packages/runtime-local/README.md
@@ -32,7 +32,7 @@ completed output is never rolled back.
`results` is optional. Without it, Hypit uses the project's `.hypit/results` directory with no cloud
account or service. It may instead select `@hypit/build-result-s3` for a shared project repository.
-Runtime working Artifacts remain internal and Build-local; there is no ArtifactStore selector. After
+Runtime working Resources remain internal and Build-local; there is no ResourceStore selector. After
a Result is terminal, history is read from the selected repository, not Runtime SQLite.
Source imports select author packages. Runtime Profile entries select only code allowed to access files,
diff --git a/packages/runtime-local/package.json b/packages/runtime-local/package.json
index 6c35fa2c..1022a6f6 100644
--- a/packages/runtime-local/package.json
+++ b/packages/runtime-local/package.json
@@ -11,7 +11,7 @@
"./worker-process": "./src/worker-process.ts"
},
"dependencies": {
- "@hypit/artifact-store-fs": "workspace:*",
+ "@hypit/resource-store-fs": "workspace:*",
"@hypit/build-result": "workspace:*",
"@hypit/build-result-fs": "workspace:*",
"@hypit/build-result-kit": "workspace:*",
diff --git a/packages/runtime-local/src/config.ts b/packages/runtime-local/src/config.ts
index d3488dd6..de2e7265 100644
--- a/packages/runtime-local/src/config.ts
+++ b/packages/runtime-local/src/config.ts
@@ -13,7 +13,7 @@ import {
CompositeCredentialStore,
} from "@hypit/runtime";
import type { CredentialStore } from "@hypit/runtime";
-import { FileArtifactStore } from "@hypit/artifact-store-fs";
+import { FileResourceStore } from "@hypit/resource-store-fs";
import {
buildResultRepositoryHostAbi,
BuildResultRepositoryRegistry,
@@ -48,14 +48,14 @@ import { SqliteRuntimeState } from "@hypit/store-sqlite";
import { createLocalRuntime } from "./runtime.js";
import {
createLocalRuntimeArchiveControl,
- createLocalRuntimeArtifactAccess,
+ createLocalRuntimeResourceAccess,
} from "./control.js";
import { createLocalCredentialControl } from "./credentials.js";
import type {
LocalCredentialControl,
LocalRuntime,
LocalRuntimeArchiveControl,
- LocalRuntimeArtifactAccess,
+ LocalRuntimeResourceAccess,
} from "./types.js";
export type RuntimeConfigEntry = {
@@ -583,9 +583,9 @@ export async function createRuntimeFromConfig(
buildCatalog: state.catalog,
operationStore: state.operations,
dispatchStore: state.dispatch,
- artifactStore: new FileArtifactStore(resolve(root, "artifacts")),
- artifactStoreForBuild: (build) => new FileArtifactStore(buildWorkPath(root, build)),
- clearBuildArtifacts: async (build) => {
+ resourceStore: new FileResourceStore(resolve(root, "resources")),
+ resourceStoreForBuild: (build) => new FileResourceStore(buildWorkPath(root, build)),
+ clearBuildResources: async (build) => {
await rm(buildWorkPath(root, build), { recursive: true, force: true });
},
openBuildResultRepository: async (location) => await openBuildResultLocation(location, options, packageRoot, resultRegistry),
@@ -626,13 +626,13 @@ export async function createRuntimeArchiveFromConfig(
});
}
-export async function createRuntimeArtifactAccessFromConfig(
+export async function createRuntimeResourceAccessFromConfig(
path: string,
options: LoadRuntimeConfigOptions = {},
-): Promise<LocalRuntimeArtifactAccess> {
+): Promise<LocalRuntimeResourceAccess> {
const { root } = await openRuntimeConfig(path, options.packageRoot);
- return createLocalRuntimeArtifactAccess({
- artifactStore: new FileArtifactStore(resolve(root, "artifacts")),
+ return createLocalRuntimeResourceAccess({
+ resourceStore: new FileResourceStore(resolve(root, "resources")),
});
}
diff --git a/packages/runtime-local/src/control.ts b/packages/runtime-local/src/control.ts
index 1bec8414..f9ca1740 100644
--- a/packages/runtime-local/src/control.ts
+++ b/packages/runtime-local/src/control.ts
@@ -1,15 +1,15 @@
import {
- isStreamingArtifactStore,
+ isStreamingResourceStore,
} from "@hypit/runtime";
import type {
CreateLocalRuntimeArchiveControlOptions,
- CreateLocalRuntimeArtifactAccessOptions,
+ CreateLocalRuntimeResourceAccessOptions,
LocalRuntimeArchiveControl,
- LocalRuntimeArtifactAccess,
+ LocalRuntimeResourceAccess,
} from "./types.js";
-/** Durable execution-state control that never opens or depends on an ArtifactStore. */
+/** Durable execution-state control that never opens or depends on a ResourceStore. */
export function createLocalRuntimeArchiveControl(
options: CreateLocalRuntimeArchiveControlOptions,
): LocalRuntimeArchiveControl {
@@ -62,17 +62,17 @@ export function createLocalRuntimeArchiveControl(
};
}
-/** Explicit Artifact byte access with no dependency on execution-state Stores. */
-export function createLocalRuntimeArtifactAccess(
- options: CreateLocalRuntimeArtifactAccessOptions,
-): LocalRuntimeArtifactAccess {
+/** Explicit active-resource byte access with no dependency on execution-state Stores. */
+export function createLocalRuntimeResourceAccess(
+ options: CreateLocalRuntimeResourceAccessOptions,
+): LocalRuntimeResourceAccess {
return {
- async readArtifact(digest) {
- return await options.artifactStore.get(digest);
+ async readResource(resource) {
+ return await options.resourceStore.get(resource);
},
- async openArtifact(digest) {
- if (isStreamingArtifactStore(options.artifactStore)) return await options.artifactStore.open(digest);
- const bytes = await options.artifactStore.get(digest);
+ async openResource(resource) {
+ if (isStreamingResourceStore(options.resourceStore)) return await options.resourceStore.open(resource);
+ const bytes = await options.resourceStore.get(resource);
return bytes === undefined ? undefined : (async function* () { yield bytes; })();
},
close() {
diff --git a/packages/runtime-local/src/host.ts b/packages/runtime-local/src/host.ts
index 0e8c71e0..902dc38c 100644
--- a/packages/runtime-local/src/host.ts
+++ b/packages/runtime-local/src/host.ts
@@ -8,7 +8,7 @@ import { resolve } from "node:path";
import {
createRuntimeArchiveFromConfig,
- createRuntimeArtifactAccessFromConfig,
+ createRuntimeResourceAccessFromConfig,
createRuntimeCredentialsFromConfig,
createRuntimeFromConfig,
doctorRuntimeConfig,
@@ -105,7 +105,7 @@ export async function openLocalRuntimeHost(
...distribution,
...(options?.readOnly === undefined ? {} : { readOnly: options.readOnly }),
}),
- openArtifacts: async () => await createRuntimeArtifactAccessFromConfig(profile, {
+ openResources: async () => await createRuntimeResourceAccessFromConfig(profile, {
packageRoot: basePackageRoot,
...distribution,
}),
diff --git a/packages/runtime-local/src/index.ts b/packages/runtime-local/src/index.ts
index 73e12522..38d255c6 100644
--- a/packages/runtime-local/src/index.ts
+++ b/packages/runtime-local/src/index.ts
@@ -1,6 +1,6 @@
export {
createLocalRuntimeArchiveControl,
- createLocalRuntimeArtifactAccess,
+ createLocalRuntimeResourceAccess,
} from "./control.js";
export { createLocalCredentialControl } from "./credentials.js";
export {
@@ -10,7 +10,7 @@ export { openLocalRuntimeHost } from "./host.js";
export {
createRuntimeFromConfig,
createRuntimeArchiveFromConfig,
- createRuntimeArtifactAccessFromConfig,
+ createRuntimeResourceAccessFromConfig,
createRuntimeCredentialsFromConfig,
openBuildResultRepositoryFromConfig,
declaredManagedPrograms,
diff --git a/packages/runtime-local/src/runtime.ts b/packages/runtime-local/src/runtime.ts
index ab019c30..6c591eae 100644
--- a/packages/runtime-local/src/runtime.ts
+++ b/packages/runtime-local/src/runtime.ts
@@ -8,11 +8,11 @@ import {
EndpointRegistry,
} from "@hypit/driver-node";
import {
- isStreamingArtifactStore,
+ isStreamingResourceStore,
} from "@hypit/runtime";
import { TypeValidatorRegistry } from "@hypit/validation";
-import { createLocalRuntimeArchiveControl, createLocalRuntimeArtifactAccess } from "./control.js";
+import { createLocalRuntimeArchiveControl, createLocalRuntimeResourceAccess } from "./control.js";
import { createLocalCredentialControl } from "./credentials.js";
import { createDurableLocalWorker } from "./worker.js";
import type {
@@ -86,8 +86,8 @@ export async function createLocalRuntime(
const driver = new NodeDriver({
producers,
endpoints,
- artifacts: options.artifactStore,
- ...(options.artifactStoreForBuild === undefined ? {} : { artifactsForBuild: options.artifactStoreForBuild }),
+ resources: options.resourceStore,
+ ...(options.resourceStoreForBuild === undefined ? {} : { resourcesForBuild: options.resourceStoreForBuild }),
credentials: options.credentialStore,
operations: options.operationStore,
validators,
@@ -99,9 +99,9 @@ export async function createLocalRuntime(
operations: options.operationStore,
dispatch: options.dispatchStore,
},
- artifactStore: options.artifactStore,
- ...(options.artifactStoreForBuild === undefined ? {} : { artifactStoreForBuild: options.artifactStoreForBuild }),
- ...(options.clearBuildArtifacts === undefined ? {} : { clearBuildArtifacts: options.clearBuildArtifacts }),
+ resourceStore: options.resourceStore,
+ ...(options.resourceStoreForBuild === undefined ? {} : { resourceStoreForBuild: options.resourceStoreForBuild }),
+ ...(options.clearBuildResources === undefined ? {} : { clearBuildResources: options.clearBuildResources }),
openBuildResultRepository: async (location) => {
assert(openBuildResultRepository !== undefined, "this Runtime cannot open Build Result Repositories");
return await openBuildResultRepository(location);
@@ -118,17 +118,18 @@ export async function createLocalRuntime(
operationStore: options.operationStore,
dispatchStore: options.dispatchStore,
});
- const artifacts = createLocalRuntimeArtifactAccess({
- artifactStore: options.artifactStore,
+ const resources = createLocalRuntimeResourceAccess({
+ resourceStore: options.resourceStore,
});
const stageAttachments = async (request: LocalBuildRequest): Promise<void> => {
- const artifactStore = options.artifactStoreForBuild?.(request.id) ?? options.artifactStore;
+ const resourceStore = options.resourceStoreForBuild?.(request.id) ?? options.resourceStore;
for (const item of request.attachments ?? []) {
- if (await artifactStore.has(item.artifact.digest)) continue;
+ if (await resourceStore.has(item.artifact.resource)) continue;
const stream = await item.open();
- const stored = isStreamingArtifactStore(artifactStore)
- ? await artifactStore.putStream(stream, item.artifact.mediaType)
- : await artifactStore.put(await (async () => {
+ if (isStreamingResourceStore(resourceStore)) {
+ await resourceStore.writeStream(item.artifact, stream);
+ } else {
+ await resourceStore.write(item.artifact, await (async () => {
const chunks: Uint8Array[] = [];
let size = 0;
for await (const chunk of stream) {
@@ -142,13 +143,8 @@ export async function createLocalRuntime(
offset += chunk.byteLength;
}
return bytes;
- })(), item.artifact.mediaType);
- assert(
- stored.digest === item.artifact.digest
- && stored.size === item.artifact.size
- && stored.mediaType === item.artifact.mediaType,
- `Source Artifact ${item.artifact.digest} does not match its staged bytes`,
- );
+ })());
+ }
}
};
const presentation = async (build: string, previousState?: LocalBuildSubmission["state"]): Promise<LocalBuildSubmission> => {
@@ -226,7 +222,7 @@ export async function createLocalRuntime(
};
return {
...archive,
- ...artifacts,
+ ...resources,
...credentialControl,
build: runBuild,
async workOnce() {
diff --git a/packages/runtime-local/src/types.ts b/packages/runtime-local/src/types.ts
index f2716a80..070e1693 100644
--- a/packages/runtime-local/src/types.ts
+++ b/packages/runtime-local/src/types.ts
@@ -3,7 +3,7 @@ import type { EndpointPackage } from "@hypit/endpoint-kit";
import type { LoadedComponentPackage } from "@hypit/package-loader-node";
import type { BuildResultRepositoryLocation, BuildResultRepositoryOpened } from "@hypit/build-result-kit";
import type {
- ArtifactStore,
+ ResourceStore,
BuildCatalog,
BuildStore,
BuildDispatchStore,
@@ -13,7 +13,7 @@ import type {
} from "@hypit/runtime";
import type {
RuntimeHostArchive,
- RuntimeHostArtifactAccess,
+ RuntimeHostResourceAccess,
RuntimeHostBuildSubmission,
RuntimeHostCredentialControl,
RuntimeHostExecution,
@@ -25,11 +25,11 @@ export type CreateLocalRuntimeOptions = {
readonly buildCatalog?: BuildCatalog;
readonly operationStore: OperationStore;
readonly dispatchStore: import("@hypit/runtime").BuildDispatchStore;
- readonly artifactStore: ArtifactStore;
+ readonly resourceStore: ResourceStore;
/** Optional Build-local transient byte area used by Provider execution and Result writing. */
- readonly artifactStoreForBuild?: (build: string) => ArtifactStore;
+ readonly resourceStoreForBuild?: (build: string) => ResourceStore;
/** Called only after a terminal Build Result has accepted every public Output completed so far. */
- readonly clearBuildArtifacts?: (build: string) => Awaitable<void>;
+ readonly clearBuildResources?: (build: string) => Awaitable<void>;
readonly openBuildResultRepository?: (location: BuildResultRepositoryLocation) => Awaitable<BuildResultRepositoryOpened>;
readonly credentialStore: CredentialStore;
readonly components?: readonly ComponentPackage[];
@@ -48,8 +48,8 @@ export type CreateLocalRuntimeArchiveControlOptions = {
readonly close?: () => Awaitable<void>;
};
-export type CreateLocalRuntimeArtifactAccessOptions = {
- readonly artifactStore: ArtifactStore;
+export type CreateLocalRuntimeResourceAccessOptions = {
+ readonly resourceStore: ResourceStore;
/** Optional owner supplied by the Runtime assembly. */
readonly close?: () => Awaitable<void>;
};
@@ -68,11 +68,11 @@ export type LocalRuntime = RuntimeHostExecution & {
workOnce(): Promise<BuildDispatchSnapshot | undefined>;
};
-/** Durable execution-state archive that never opens the selected ArtifactStore. */
+/** Durable execution-state archive that never opens the selected ResourceStore. */
export type LocalRuntimeArchiveControl = RuntimeHostArchive;
/** Explicit Artifact byte access that never opens Build, Operation or Dispatch state. */
-export type LocalRuntimeArtifactAccess = RuntimeHostArtifactAccess;
+export type LocalRuntimeResourceAccess = RuntimeHostResourceAccess;
/** Credential control for one or more exact Endpoint declarations; no execution state is opened. */
export type LocalCredentialControl = RuntimeHostCredentialControl;
diff --git a/packages/runtime-local/src/worker.ts b/packages/runtime-local/src/worker.ts
index d3b8e1e7..26f89b8f 100644
--- a/packages/runtime-local/src/worker.ts
+++ b/packages/runtime-local/src/worker.ts
@@ -1,7 +1,7 @@
import type { BuildState } from "@hypit/protocol";
import type { BuildResultWriter } from "@hypit/build-result";
import type {
- ArtifactStore,
+ ResourceStore,
BuildDispatchSnapshot,
RuntimeCommandExecutor,
RuntimeExecutionResult,
@@ -10,7 +10,7 @@ import type {
ScheduledBuildResult,
RuntimeWorkerRunOptions,
} from "@hypit/runtime";
-import { isStreamingArtifactStore, LocalBuildScheduler } from "@hypit/runtime";
+import { isStreamingResourceStore, LocalBuildScheduler } from "@hypit/runtime";
type LocalWorkerOptions = {
readonly stores: {
@@ -19,9 +19,9 @@ type LocalWorkerOptions = {
readonly operations: import("@hypit/runtime").OperationStore;
readonly dispatch: import("@hypit/runtime").BuildDispatchStore;
};
- readonly artifactStore: ArtifactStore;
- readonly artifactStoreForBuild?: (build: string) => ArtifactStore;
- readonly clearBuildArtifacts?: (build: string) => Promise<void> | void;
+ readonly resourceStore: ResourceStore;
+ readonly resourceStoreForBuild?: (build: string) => ResourceStore;
+ readonly clearBuildResources?: (build: string) => Promise<void> | void;
readonly openBuildResultRepository: NonNullable<import("./types.js").CreateLocalRuntimeOptions["openBuildResultRepository"]>;
readonly installComponentPackages: (specifiers: readonly string[]) => Promise<void>;
};
@@ -172,15 +172,15 @@ class DurableLocalWorker {
const result = await this.#openResult(dispatch);
if (result === undefined) return;
try {
- const artifactStore = this.#options.artifactStoreForBuild?.(dispatch.build) ?? this.#options.artifactStore;
+ const resourceStore = this.#options.resourceStoreForBuild?.(dispatch.build) ?? this.#options.resourceStore;
await result.writer.sync({
state,
- artifacts: {
+ resources: {
open: async (artifact) => {
- if (isStreamingArtifactStore(artifactStore)) {
- return await artifactStore.open(artifact.digest);
+ if (isStreamingResourceStore(resourceStore)) {
+ return await resourceStore.open(artifact.resource);
}
- const bytes = await artifactStore.get(artifact.digest);
+ const bytes = await resourceStore.get(artifact.resource);
return bytes === undefined ? undefined : (async function* () { yield bytes; })();
},
},
@@ -207,7 +207,7 @@ class DurableLocalWorker {
async #retireExecution(build: string): Promise<void> {
await Promise.allSettled([
- this.#options.clearBuildArtifacts?.(build),
+ this.#options.clearBuildResources?.(build),
this.#options.stores.operations.removeBuild?.(build),
this.#options.stores.builds.remove?.(build),
this.#options.stores.catalog?.remove?.(build),
diff --git a/packages/runtime-local/test/config.test.ts b/packages/runtime-local/test/config.test.ts
index 75a6fb2c..da9b4a8b 100644
--- a/packages/runtime-local/test/config.test.ts
+++ b/packages/runtime-local/test/config.test.ts
@@ -17,7 +17,7 @@ import { FileBuildResultRepository } from "@hypit/build-result";
import { SqliteRuntimeState } from "@hypit/store-sqlite";
import {
createRuntimeArchiveFromConfig,
- createRuntimeArtifactAccessFromConfig,
+ createRuntimeResourceAccessFromConfig,
doctorRuntimeConfig,
openBuildResultRepositoryFromConfig,
parseRuntimeConfig,
@@ -121,7 +121,7 @@ test("Runtime Profile rejects source ownership fields", () => {
assert.throws(() => parseRuntimeConfig({ ...profile(), root: "." }), /does not accept root/u);
});
-test("archive inspection and working Artifact access require no selected ArtifactStore", async () => {
+test("archive inspection and working Resource access require no selected ResourceStore", async () => {
const root = await mkdtemp(join(tmpdir(), "hypit-runtime-slice-"));
const path = join(root, "hypit.runtime.json");
await writeFile(path, JSON.stringify(profile({ dataRoot: "." })));
@@ -132,8 +132,8 @@ test("archive inspection and working Artifact access require no selected Artifac
const archive = await createRuntimeArchiveFromConfig(path, { registry, readOnly: true });
assert.equal((await archive.status("missing")).build, undefined);
await archive.close();
- const artifacts = await createRuntimeArtifactAccessFromConfig(path, { registry });
- assert.equal(await artifacts.readArtifact("sha256:0000000000000000000000000000000000000000000000000000000000000000"), undefined);
+ const artifacts = await createRuntimeResourceAccessFromConfig(path, { registry });
+ assert.equal(await artifacts.readResource("res_missing"), undefined);
await artifacts.close();
} finally {
await rm(root, { recursive: true, force: true });
diff --git a/packages/runtime-local/test/local.test.ts b/packages/runtime-local/test/local.test.ts
index fafa0112..cbdcc5cb 100644
--- a/packages/runtime-local/test/local.test.ts
+++ b/packages/runtime-local/test/local.test.ts
@@ -11,7 +11,7 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import test from "node:test";
-import { FileArtifactStore } from "@hypit/artifact-store-fs";
+import { FileResourceStore } from "@hypit/resource-store-fs";
import { FileBuildResultRepository, readBuildResult } from "@hypit/build-result";
import { EnvironmentCredentialStore } from "@hypit/credential-store-env";
import { defineEndpointPackage } from "@hypit/endpoint-kit";
@@ -49,9 +49,9 @@ function projectRuntimeFixture(directory: string) {
buildCatalog: state.catalog,
operationStore: state.operations,
dispatchStore: state.dispatch,
- artifactStore: new FileArtifactStore(join(directory, ".hypit", "artifacts")),
- artifactStoreForBuild: (build: string) => new FileArtifactStore(join(work, build)),
- clearBuildArtifacts: async (build: string) => {
+ resourceStore: new FileResourceStore(join(directory, ".hypit", "artifacts")),
+ resourceStoreForBuild: (build: string) => new FileResourceStore(join(work, build)),
+ clearBuildResources: async (build: string) => {
await rm(join(work, build), { recursive: true, force: true });
},
openBuildResultRepository: async (location: import("@hypit/build-result-kit").BuildResultRepositoryLocation) => {
@@ -280,7 +280,7 @@ test("project local runtime queues, polls and cancels work with replaceable pack
test("a completed public file moves into its Build Result and leaves no Runtime working copy", async () => {
const directory = await mkdtemp(join(tmpdir(), "hypit-local-result-file-"));
const id = "public-file-result";
- const workStore = new FileArtifactStore(join(directory, ".hypit", "work", id));
+ const workStore = new FileResourceStore(join(directory, ".hypit", "work", id));
const initial = createGreetingBuild({ generationRealization: "placeholder" });
const buildDefinition = defineBuild(initial.program, initial.graph, sealBuildRequest({
targets: [{ output: "generated" }],
diff --git a/packages/runtime/README.md b/packages/runtime/README.md
index 77b2d61d..f486762e 100644
--- a/packages/runtime/README.md
+++ b/packages/runtime/README.md
@@ -7,7 +7,7 @@ The package defines the small ports used by a runtime:
* `BuildStore` keeps one active Build definition and its accepted facts until its Result is terminal.
* `OperationStore` keeps asynchronous external work only while the owning Build is active.
* `BuildDispatchStore` holds the local build queue and shared capacity reservations.
-* `ArtifactStore` is the transient byte gateway used during Provider execution.
+* `ResourceStore` is the transient byte gateway used during Provider execution.
* `CredentialStore` resolves secrets outside source and build state.
* `RuntimeCommandExecutor` turns the commands regenerated by Core into component or endpoint calls.
* `LocalBuildScheduler` runs ready commands concurrently while respecting declared resource limits.
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index 5c6d79c0..6cadee4d 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -12,6 +12,6 @@ export type * from "./dispatch.js";
export type * from "./operations.js";
export { LocalBuildScheduler } from "./scheduler.js";
export {
- isStreamingArtifactStore,
+ isStreamingResourceStore,
} from "./types.js";
export type * from "./types.js";
diff --git a/packages/runtime/src/types.ts b/packages/runtime/src/types.ts
index 6e7bb73c..f61ef915 100644
--- a/packages/runtime/src/types.ts
+++ b/packages/runtime/src/types.ts
@@ -5,7 +5,7 @@ import type {
BuildState,
CommandResult,
CoreCommand,
- Digest,
+ ResourceId,
} from "@hypit/protocol";
import type { OperationSnapshot } from "./operations.js";
@@ -70,25 +70,29 @@ export type RuntimeCommandExecutor = {
): Promise<OperationSnapshot>;
};
-/** Content-addressed bytes. Location, retention and remote transport are adapter policy. */
-export type ArtifactStore = {
- /** Admit bytes and compute their identity in the same pass. */
+/** Build-local byte resources. Location, retention and transport are Runtime policy. */
+export type ResourceStore = {
+ /** Store one new resource instance. Equal bytes remain independent resources. */
put(bytes: Uint8Array, mediaType: string): Promise<BlobRef>;
- /** Read bytes previously admitted under this digest. */
- get(digest: Digest): Promise<Uint8Array | undefined>;
+ /** Write bytes for an already-declared source or historical resource. */
+ write(resource: BlobRef, bytes: Uint8Array): Promise<void>;
+ /** Read bytes previously stored under this execution identity. */
+ get(resource: ResourceId): Promise<Uint8Array | undefined>;
/** Cheap presence query. */
- has(digest: Digest): Promise<boolean>;
+ has(resource: ResourceId): Promise<boolean>;
};
/** Optional transfer capability. Core and components never require storage to expose it. */
-export type StreamingArtifactStore = ArtifactStore & {
+export type StreamingResourceStore = ResourceStore & {
putStream(chunks: AsyncIterable<Uint8Array>, mediaType: string): Promise<BlobRef>;
- /** Stream bytes previously admitted under this digest. */
- open(digest: Digest): Promise<AsyncIterable<Uint8Array> | undefined>;
+ writeStream(resource: BlobRef, chunks: AsyncIterable<Uint8Array>): Promise<void>;
+ /** Stream bytes previously stored under this resource identity. */
+ open(resource: ResourceId): Promise<AsyncIterable<Uint8Array> | undefined>;
};
-export function isStreamingArtifactStore(value: ArtifactStore): value is StreamingArtifactStore {
+export function isStreamingResourceStore(value: ResourceStore): value is StreamingResourceStore {
return "putStream" in value && typeof value.putStream === "function"
+ && "writeStream" in value && typeof value.writeStream === "function"
&& "open" in value && typeof value.open === "function";
}
diff --git a/packages/screen-overlay/test/screen-overlay.test.ts b/packages/screen-overlay/test/screen-overlay.test.ts
index 74432781..fe52a4d4 100644
--- a/packages/screen-overlay/test/screen-overlay.test.ts
+++ b/packages/screen-overlay/test/screen-overlay.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import { projectProgramWindow } from "../../../test/temporal-fixture.js";
@@ -136,7 +136,7 @@ test("the package has no lower-composite, sibling Track, backdrop-filter or hidd
test("the self-described Screen Surface parses into a finite peer-Track graph", async () => {
const fixtureModule = { name: "example.screen-inputs", version: "1" } as const;
- const fixtureSurfaceDigest = fixtureDigest("example.screen-inputs/surface@1");
+ const fixtureSurfaceDigest = fixtureResource("example.screen-inputs/surface@1");
const fixtureSurface = {
name: "inputs", tag: "Inputs", mode: "structured",
outputs: [spatialTypes.canvas, semanticTrackTypes.track],
diff --git a/packages/seedance/src/index.ts b/packages/seedance/src/index.ts
index a62671fa..d31b77a3 100644
--- a/packages/seedance/src/index.ts
+++ b/packages/seedance/src/index.ts
@@ -19,7 +19,7 @@ import { assertSpeechDurationIdentity, speechDependency, speechTypes } from "@hy
import type { SpeechDuration } from "@hypit/speech";
import { textTypes } from "@hypit/text";
import { canonicalize } from "@hypit/protocol";
-import type { Digest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import type { ResourceId, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
export const seedanceModuleRef = { name: "@hypit/seedance", version: "1" } as const;
export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2.5"] as const;
diff --git a/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts b/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts
index 6e7a27cc..12b14d9a 100644
--- a/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts
+++ b/packages/semantic-take-adjust/test/semantic-take-adjust.test.ts
@@ -9,7 +9,7 @@ const source = {
media: {
timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 100 },
visual: {
- artifact: { kind: "blob", digest: `sha256:${"0".repeat(64)}`, size: 1, mediaType: "video/mp4" },
+ artifact: { kind: "blob", resource: "res_semantic-take-adjust", size: 1, mediaType: "video/mp4" },
width: 720,
height: 1280,
},
diff --git a/packages/semantic-take-estimate/test/semantic-take-estimate.test.ts b/packages/semantic-take-estimate/test/semantic-take-estimate.test.ts
index 819eecc6..9151bdc2 100644
--- a/packages/semantic-take-estimate/test/semantic-take-estimate.test.ts
+++ b/packages/semantic-take-estimate/test/semantic-take-estimate.test.ts
@@ -4,7 +4,7 @@ import test from "node:test";
import { sealSpeechEstimatePolicy } from "@hypit/estimate";
import { sealSynchronizedMedia } from "@hypit/media";
import type { Narrative } from "@hypit/narrative";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import {
estimateSemanticTakeTiming,
@@ -46,7 +46,7 @@ const excerpt = { narrativeId: narrative.id, kind: "segment" as const, id: "open
const media = sealSynchronizedMedia({
timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 120 },
visual: {
- artifact: { kind: "blob", digest: fixtureDigest("estimated-take-video"), size: 1_024, mediaType: "video/mp4" },
+ artifact: { kind: "blob", resource: fixtureResource("estimated-take-video"), size: 1_024, mediaType: "video/mp4" },
width: 1_080,
height: 1_920,
},
diff --git a/packages/speech-alignment/src/locate.ts b/packages/speech-alignment/src/locate.ts
index 027fd3ed..da7a546b 100644
--- a/packages/speech-alignment/src/locate.ts
+++ b/packages/speech-alignment/src/locate.ts
@@ -1,4 +1,4 @@
-import { isDigest } from "@hypit/protocol";
+import { isResourceId } from "@hypit/protocol";
import type { BlobRef } from "@hypit/protocol";
import type { Narrative, NarrativeToken } from "@hypit/narrative";
import { programFrameSampleBoundary, programSpaceFrameCount } from "@hypit/program-space";
@@ -96,7 +96,7 @@ function validateBasis(narrative: Narrative, basis: AlignmentBasis): void {
fail("SPEECH_FRAME_RATE", "ProgramSpace frame rate must be a positive rational number.");
}
const frameCount = programSpaceFrameCount(basis.programSpace);
- if (basis.audio.kind !== "blob" || !isDigest(basis.audio.digest)
+ if (basis.audio.kind !== "blob" || !isResourceId(basis.audio.resource)
|| basis.audio.mediaType !== "audio/wav" || !Number.isSafeInteger(basis.audio.size) || basis.audio.size < 0) {
fail("SPEECH_AUDIO_DIGEST", "Speech alignment audio BlobRef is invalid.");
}
diff --git a/packages/speech-alignment/test/speech-align.test.ts b/packages/speech-alignment/test/speech-align.test.ts
index c307dc41..2aa321f3 100644
--- a/packages/speech-alignment/test/speech-align.test.ts
+++ b/packages/speech-alignment/test/speech-align.test.ts
@@ -5,7 +5,7 @@ import { sealAlignedTranscriptEvidence } from "@hypit/speech-evidence";
import type { AlignedTranscriptEvidence, SpeechCharacterEvidence, SpeechWordEvidence } from "@hypit/speech-evidence";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { narrativeValue, parseScript as parseScriptSource } from "@hypit/script";
import {
@@ -85,10 +85,10 @@ function speechBasis(
durationSec,
frameRate: { numerator: 1_000, denominator: 1 },
});
- const audioDigest = fixtureDigest(`fixture:audio:${narrative.segments.map((segment) => segment.id).join("+")}:${durationSec}`);
+ const audioDigest = fixtureResource(`fixture:audio:${narrative.segments.map((segment) => segment.id).join("+")}:${durationSec}`);
return {
programSpace,
- audio: { kind: "blob", digest: audioDigest, size: 1, mediaType: "audio/wav" },
+ audio: { kind: "blob", resource: audioDigest, size: 1, mediaType: "audio/wav" },
segments: [{
segmentId: narrative.segments[0]!.id,
startFrame: 0,
@@ -157,8 +157,8 @@ test("a measured Segment-local map becomes a self-contained SemanticTake", () =>
{ narrativeId: narrative.id, kind: "segment", id: segment.id, tokenStart: segment.tokenStart, tokenEndExclusive: segment.tokenEndExclusive },
{
timeline: { frameRate: { numerator: 1_000, denominator: 1 }, frameCount: 2_000 },
- visual: { artifact: { kind: "blob", digest: fixtureDigest("materialize:video"), size: 1, mediaType: "video/mp4" }, width: 720, height: 1280 },
- audio: { artifact: { kind: "blob", digest: fixtureDigest("materialize:audio"), size: 1, mediaType: "audio/wav" } },
+ visual: { artifact: { kind: "blob", resource: fixtureResource("materialize:video"), size: 1, mediaType: "video/mp4" }, width: 720, height: 1280 },
+ audio: { artifact: { kind: "blob", resource: fixtureResource("materialize:audio"), size: 1, mediaType: "audio/wav" } },
},
map,
);
diff --git a/packages/speech-track-studio/src/index.ts b/packages/speech-track-studio/src/index.ts
index ca8fc46b..e3916dc9 100644
--- a/packages/speech-track-studio/src/index.ts
+++ b/packages/speech-track-studio/src/index.ts
@@ -44,7 +44,7 @@ type SpeechVisualTrack = {
readonly subjectId?: string;
readonly elements?: readonly {
readonly kind?: string;
- readonly artifact?: { readonly digest?: string };
+ readonly artifact?: { readonly resource?: string };
}[];
}[];
};
@@ -53,7 +53,7 @@ type SpeechAudioTrack = {
readonly clips?: readonly {
readonly id: string;
readonly subjectId?: string;
- readonly artifact?: { readonly digest?: string };
+ readonly artifact?: { readonly resource?: string };
}[];
};
@@ -65,14 +65,14 @@ function projectSpeechVisual(context: StudioTrackCompanionContext): readonly Stu
const present = presents.get(id);
const subjectId = present?.subjectId;
const artifact = present?.elements?.find((element) =>
- (element.kind === "image" || element.kind === "video") && element.artifact?.digest !== undefined)?.artifact;
+ (element.kind === "image" || element.kind === "video") && element.artifact?.resource !== undefined)?.artifact;
return {
...entity,
authoredId: subjectId ?? id,
...(context.placement === undefined ? {} : { elementRange: context.placement.range }),
display: {
title: subjectId ?? "Speech",
- layers: artifact?.digest === undefined ? [] : [previewLayer(artifactPreview("video", artifact.digest), "storyboard")],
+ layers: artifact?.resource === undefined ? [] : [previewLayer(artifactPreview("video", artifact.resource), "storyboard")],
},
presentation: { entity: "media-item", chrome: "standard" },
};
@@ -91,7 +91,7 @@ function projectSpeechAudio(context: StudioTrackCompanionContext): readonly Stud
authoredId: subjectId ?? id,
display: {
title: subjectId ?? entity.authoredId,
- layers: clip?.artifact?.digest === undefined ? [] : [previewLayer(artifactPreview("audio", clip.artifact.digest), "waveform")],
+ layers: clip?.artifact?.resource === undefined ? [] : [previewLayer(artifactPreview("audio", clip.artifact.resource), "waveform")],
},
presentation: { entity: "audio-clip", chrome: "standard" },
};
diff --git a/packages/speech-track/test/program.test.ts b/packages/speech-track/test/program.test.ts
index e08e8410..218ff5b5 100644
--- a/packages/speech-track/test/program.test.ts
+++ b/packages/speech-track/test/program.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import type { SynchronizedMedia } from "@hypit/media";
import type { SemanticTake } from "@hypit/speech";
@@ -26,11 +26,11 @@ function semantic(id: string, visual: boolean): SemanticTake {
const media: SynchronizedMedia = {
timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },
...(visual ? { visual: {
- artifact: { kind: "blob", digest: fixtureDigest(`${id}:video`), size: 1, mediaType: "video/mp4" },
+ artifact: { kind: "blob", resource: fixtureResource(`${id}:video`), size: 1, mediaType: "video/mp4" },
width: 720,
height: 1280,
} } : {}),
- audio: { artifact: { kind: "blob", digest: fixtureDigest(`${id}:audio`), size: 1, mediaType: "audio/wav" } },
+ audio: { artifact: { kind: "blob", resource: fixtureResource(`${id}:audio`), size: 1, mediaType: "audio/wav" } },
};
return {
narrativeId: "test-narrative",
diff --git a/packages/speech-track/test/surface.test.ts b/packages/speech-track/test/surface.test.ts
index 8d6ca9e3..106d33a8 100644
--- a/packages/speech-track/test/surface.test.ts
+++ b/packages/speech-track/test/surface.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import type { StructuredElement, SurfaceResolvedReference } from "@hypit/markup";
import type { SemanticTake } from "@hypit/speech";
@@ -14,12 +14,12 @@ const take: SemanticTake = {
media: {
timeline: { frameRate: { numerator: 30, denominator: 1 }, frameCount: 30 },
visual: {
- artifact: { kind: "blob", digest: fixtureDigest("track:take:video"), size: 1, mediaType: "video/mp4" },
+ artifact: { kind: "blob", resource: fixtureResource("track:take:video"), size: 1, mediaType: "video/mp4" },
width: 720,
height: 1280,
},
audio: {
- artifact: { kind: "blob", digest: fixtureDigest("track:take:audio"), size: 1, mediaType: "audio/wav" },
+ artifact: { kind: "blob", resource: fixtureResource("track:take:audio"), size: 1, mediaType: "audio/wav" },
},
},
segment: {
diff --git a/packages/speech/src/identity.ts b/packages/speech/src/identity.ts
index a83365f2..91fef43f 100644
--- a/packages/speech/src/identity.ts
+++ b/packages/speech/src/identity.ts
@@ -1,4 +1,4 @@
-import { isDigest } from "@hypit/protocol";
+import { isResourceId } from "@hypit/protocol";
import { verifySynchronizedMedia } from "@hypit/media";
import type { SemanticTake, SpeechDuration, SpeechEvidenceAudio } from "./types.js";
export function sealSpeechDuration(value: SpeechDuration): SpeechDuration { return value; }
@@ -65,7 +65,7 @@ export function assertSemanticTakeIdentity(take: SemanticTake): void {
}
}
export function assertSpeechEvidenceAudioIdentity(value: SpeechEvidenceAudio): void {
- if (value.artifact.kind !== "blob" || !isDigest(value.artifact.digest)
+ if (value.artifact.kind !== "blob" || !isResourceId(value.artifact.resource)
|| !Number.isSafeInteger(value.artifact.size) || value.artifact.size < 0 || value.artifact.mediaType !== "audio/wav"
|| !Number.isSafeInteger(value.sampleFrames) || value.sampleFrames < 1) {
throw new Error("SpeechEvidenceAudio media identity is invalid.");
diff --git a/packages/speech/src/schema.ts b/packages/speech/src/schema.ts
index c8a1731f..860528b9 100644
--- a/packages/speech/src/schema.ts
+++ b/packages/speech/src/schema.ts
@@ -3,11 +3,11 @@ import type { ValueSchema } from "@hypit/protocol";
const string = { kind: "string", minLength: 1 } as const;
const number = { kind: "number", minimum: 0 } as const;
const integer = { kind: "number", integer: true, minimum: 0 } as const;
-const digest = { kind: "string", minLength: 71, maxLength: 71 } as const;
+const digest = { kind: "string", minLength: 5, maxLength: 256 } as const;
const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
const audioBlobRef = object({
kind: { schema: { kind: "literal", value: "blob" } },
- digest: { schema: digest },
+ resource: { schema: digest },
size: { schema: integer },
mediaType: { schema: { kind: "literal", value: "audio/wav" } },
});
diff --git a/packages/speech/test/evidence.test.ts b/packages/speech/test/evidence.test.ts
index fa991a5c..c0ad5c60 100644
--- a/packages/speech/test/evidence.test.ts
+++ b/packages/speech/test/evidence.test.ts
@@ -3,7 +3,7 @@ import { assertSpeechEvidenceAudioIdentity, sealSpeechEvidenceAudio, speechEvide
import type { SpeechEvidenceAudio } from "@hypit/speech";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
test("speech evidence uses integer rational boundary projection rather than floating duration arithmetic", () => {
@@ -22,7 +22,7 @@ test("SpeechEvidenceAudio carries only normalized evidence bytes and their exact
const value = sealSpeechEvidenceAudio({
artifact: {
kind: "blob",
- digest: fixtureDigest("evidence"),
+ resource: fixtureResource("evidence"),
size: 32_044,
mediaType: "audio/wav",
},
diff --git a/packages/speech/test/identity.test.ts b/packages/speech/test/identity.test.ts
index 118f3b08..9d6bd0e1 100644
--- a/packages/speech/test/identity.test.ts
+++ b/packages/speech/test/identity.test.ts
@@ -11,7 +11,7 @@ test("SemanticTake rejects Token frames that disagree with authored Anchors", ()
audio: {
artifact: {
kind: "blob",
- digest: `sha256:${"0".repeat(64)}`,
+ resource: "res_speech-identity",
size: 1,
mediaType: "audio/wav",
},
diff --git a/packages/studio-adapter/src/index.ts b/packages/studio-adapter/src/index.ts
index d40ec124..7ffbc1d0 100644
--- a/packages/studio-adapter/src/index.ts
+++ b/packages/studio-adapter/src/index.ts
@@ -273,7 +273,7 @@ export type StudioEditHandle = {
/** A source descriptor; Companion packages never depend on Studio's HTTP routes. */
export type StudioPreviewSource =
- | { readonly kind: "artifact"; readonly digest: string }
+ | { readonly kind: "artifact"; readonly resource: string }
| {
readonly kind: "surface-preview";
readonly module: string;
@@ -728,9 +728,9 @@ export function requiredReferencedValue(
export function artifactPreview(
kind: StudioMaterialPreview["kind"],
- digest: string,
+ resource: string,
): StudioMaterialPreview {
- return { kind, source: { kind: "artifact", digest } };
+ return { kind, source: { kind: "artifact", resource } };
}
export function previewLayer(
diff --git a/packages/studio/README.md b/packages/studio/README.md
index b9b35abe..e81fe00f 100644
--- a/packages/studio/README.md
+++ b/packages/studio/README.md
@@ -16,7 +16,7 @@ boundary. The upper-left library is intentionally not a filesystem browser:
- Source is the exact Run + Author closure and writes back only the selected file;
- Tasks are read-only Build Catalog/Archive/Dispatch/Operation views;
-- Artifacts are ArtifactStore objects referenced by accepted Records.
+- Artifacts are public files exposed by project Build Results.
No project manifest, Studio database, output-directory scan or inferred campaign
folder structure is involved. With no selected Runtime, Source and Preview still
@@ -50,7 +50,7 @@ source bindings, Inspector fields and exact timeline inverses. Inspector fields
select real writable bindings and organize them under the Studio-owned
`Where / How / When` domains, optional companion-owned pages and sections. A
source binding is never shown merely because Studio can reach it. Material layers carry an
-Artifact digest or Surface identity, never a Studio HTTP URL. Studio always owns
+Resource id or Surface identity, never a Studio HTTP URL. Studio always owns
time formatting and transport resolution, so chrome and material cannot hide a
title or its time.
Studio owns session-wide behavior and chrome: Companion selection, collision and
diff --git a/packages/studio/package.json b/packages/studio/package.json
index 9aba4ab2..a713a7c0 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -10,6 +10,7 @@
},
"dependencies": {
"@hypit/audio-track-studio": "workspace:*",
+ "@hypit/build-result": "workspace:*",
"@hypit/caption-fine-studio": "workspace:*",
"@hypit/cli": "workspace:*",
"@hypit/compiler-node": "workspace:*",
diff --git a/packages/studio/src/archive.ts b/packages/studio/src/archive.ts
index c9cd20b1..2293bdd8 100644
--- a/packages/studio/src/archive.ts
+++ b/packages/studio/src/archive.ts
@@ -1,10 +1,17 @@
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
import type { BuildCatalogEntry } from "@hypit/runtime";
import type { NodeRuntimeHost, RuntimeHostStatus } from "@hypit/runtime-host-node";
-import type { Digest, StoredValue, TypeRef } from "@hypit/protocol";
+import type { StoredValue, TypeRef } from "@hypit/protocol";
+import { FileBuildResultRepository } from "@hypit/build-result";
+import type {
+ BuildResultFileRef,
+ BuildResultJsonValue,
+ BuildResultRepository,
+ RepositoryBuildResultOutput,
+} from "@hypit/build-result";
-import { collectArtifacts, selectArchivedRecord } from "@hypit/cli";
+import { resolveBuildResultRecord } from "@hypit/cli";
import { videoCliDistribution } from "@hypit/video-cli";
import type { StudioArtifactView, StudioLibraryView, StudioTaskView } from "./shared.js";
@@ -12,14 +19,22 @@ import type { StudioArtifactView, StudioLibraryView, StudioTaskView } from "./sh
type RuntimeArchive = Awaited<ReturnType<NodeRuntimeHost["openArchive"]>>;
export type StudioArchive = {
- readonly profile: string;
- readonly runtime: Pick<RuntimeArchive, "status">;
+ readonly profile?: string;
+ readonly runtime?: Pick<RuntimeArchive, "status">;
readonly library: () => Promise<StudioLibraryView>;
readonly resolveBuildRecord: (
build: string,
output: string,
- ) => Promise<{ readonly type: TypeRef; readonly value: StoredValue } | undefined>;
- readonly read: (digest: Digest) => Promise<Uint8Array | undefined>;
+ ) => Promise<{
+ readonly type: TypeRef;
+ readonly value: StoredValue;
+ readonly attachments?: readonly import("@hypit/workspace").ArtifactAttachment[];
+ } | undefined>;
+ readonly openArtifact: (
+ build: string,
+ output: string,
+ valuePath: string,
+ ) => Promise<{ readonly mediaType: string; readonly bytes: Uint8Array } | undefined>;
readonly close: () => Promise<void>;
};
@@ -80,83 +95,87 @@ function taskView(root: string, entry: BuildCatalogEntry, status: RuntimeHostSta
};
}
-function artifactsForBuild(
- root: string,
- entry: BuildCatalogEntry,
- status: RuntimeHostStatus,
-): readonly StudioArtifactView[] {
- const state = status.build?.state;
- if (state === undefined) return [];
- const outputsByRecord = new Map<string, Set<string>>();
- const recordForOutput = new Map(state.plan.selections.map((selection) => [selection.output, selection.record]));
- for (const alias of entry.aliases) {
- const record = alias.ref.kind === "record" ? alias.ref.id : recordForOutput.get(alias.ref.id);
- if (record === undefined) continue;
- const names = outputsByRecord.get(record) ?? new Set<string>();
- names.add(alias.name);
- outputsByRecord.set(record, names);
- }
+function isResultFile(value: BuildResultJsonValue): value is BuildResultFileRef {
+ if (value === null || Array.isArray(value) || typeof value !== "object") return false;
+ const item = value as Readonly<Record<string, unknown>>;
+ return item.kind === "build-file" && typeof item.path === "string"
+ && typeof item.size === "number" && typeof item.mediaType === "string";
+}
- type Held = {
- readonly digest: Digest;
- readonly size: number;
- readonly mediaType: string;
- readonly records: Set<string>;
- readonly outputs: Set<string>;
- readonly paths: Set<string>;
- };
- const found = new Map<Digest, Held>();
- for (const record of state.records) {
- const value = record.value.kind === "blob" ? record.value : record.value.value;
- for (const artifact of collectArtifacts(value)) {
- const held = found.get(artifact.digest) ?? {
- digest: artifact.digest,
- size: artifact.size,
- mediaType: artifact.mediaType,
- records: new Set<string>(),
- outputs: new Set<string>(),
- paths: new Set<string>(),
- };
- held.records.add(record.id);
- for (const output of outputsByRecord.get(record.id) ?? []) held.outputs.add(output);
- held.paths.add(`${record.id}${artifact.path === "$" ? "" : artifact.path.slice(1)}`);
- found.set(artifact.digest, held);
- }
+function filesInResultValue(
+ value: BuildResultJsonValue,
+ valuePath = "$",
+): readonly { readonly valuePath: string; readonly file: BuildResultFileRef }[] {
+ if (isResultFile(value)) {
+ return [{ valuePath, file: value }];
}
- return [...found.values()].map((artifact) => ({
- id: `${entry.build}:${artifact.digest}`,
- build: entry.build,
- createdAt: entry.createdAt,
- digest: artifact.digest,
- size: artifact.size,
- mediaType: artifact.mediaType,
- records: [...artifact.records],
- outputs: [...artifact.outputs],
- paths: [...artifact.paths],
- source: presentedPath(root, entry.source.path),
- ...(entry.run === undefined ? {} : { run: presentedPath(root, entry.run.path) }),
- })).sort((left, right) =>
- (left.outputs[0] ?? left.records[0] ?? left.digest)
- .localeCompare(right.outputs[0] ?? right.records[0] ?? right.digest));
+ if (Array.isArray(value)) {
+ return value.flatMap((item, index) => filesInResultValue(item, `${valuePath}[${index}]`));
+ }
+ if (value !== null && typeof value === "object") {
+ return Object.entries(value).flatMap(([key, item]) => filesInResultValue(item, `${valuePath}.${key}`));
+ }
+ return [];
+}
+
+function filesInResolvedOutput(resolved: RepositoryBuildResultOutput): readonly {
+ readonly valuePath: string;
+ readonly file: BuildResultFileRef;
+}[] {
+ if (resolved.value.kind === "build-file") return [{ valuePath: "$", file: resolved.value }];
+ if (resolved.value.kind === "json") return filesInResultValue(resolved.value.value);
+ return [];
}
-/** Build the Studio library from the existing Catalog, Archive and Artifact references. */
+async function artifactsForResults(
+ root: string,
+ repository: BuildResultRepository,
+): Promise<readonly StudioArtifactView[]> {
+ const manifests = (await repository.list()).filter((manifest) =>
+ isWithin(root, manifest.run?.path ?? manifest.source.path) || isWithin(root, manifest.source.path));
+ const nested = await Promise.all(manifests.flatMap((manifest) =>
+ Object.keys(manifest.outputs).map(async (output) => {
+ const resolved = await repository.resolve(manifest.id, output);
+ if (resolved === undefined) return [];
+ return filesInResolvedOutput(resolved).map(({ valuePath, file }) => ({
+ id: `${manifest.id}:${output}:${valuePath}`,
+ build: manifest.id,
+ createdAt: manifest.startedAt,
+ output,
+ valuePath,
+ ownerBuild: file.build ?? resolved.build,
+ ownerOutput: resolved.output,
+ filePath: file.path,
+ size: file.size,
+ mediaType: file.mediaType,
+ source: presentedPath(root, manifest.source.path),
+ ...(manifest.run === undefined ? {} : { run: presentedPath(root, manifest.run.path) }),
+ }));
+ })));
+ return nested.flat().sort((left, right) =>
+ right.createdAt - left.createdAt
+ || left.output.localeCompare(right.output)
+ || left.valuePath.localeCompare(right.valuePath));
+}
+
+/** Build the Studio library from execution status and project-owned Build Results. */
export async function readStudioLibrary(input: {
- readonly profile: string;
+ readonly profile?: string;
readonly workspaceRoot: string;
- readonly runtime: Pick<RuntimeArchive, "builds" | "status">;
+ readonly runtime?: Pick<RuntimeArchive, "builds" | "status">;
+ readonly results: BuildResultRepository;
}): Promise<StudioLibraryView> {
- const entries = (await input.runtime.builds())
+ const entries = (await input.runtime?.builds() ?? [])
.filter((entry) => buildBelongsTo(input.workspaceRoot, entry));
const statuses = await Promise.all(entries.map(async (entry) => ({
entry,
- status: await input.runtime.status(entry.build),
+ status: await input.runtime!.status(entry.build),
})));
return {
environment: resolve(input.workspaceRoot),
- runtime: resolve(input.profile),
+ ...(input.profile === undefined ? {} : { runtime: resolve(input.profile) }),
tasks: statuses.map(({ entry, status }) => taskView(input.workspaceRoot, entry, status)),
- artifacts: statuses.flatMap(({ entry, status }) => artifactsForBuild(input.workspaceRoot, entry, status)),
+ artifacts: await artifactsForResults(input.workspaceRoot, input.results),
};
}
@@ -167,40 +186,58 @@ export async function openStudioArchive(
workspaceRoot: string,
distributionPackageRoot?: string,
): Promise<StudioArchive | undefined> {
- if (profile === undefined) return undefined;
- const resolvedProfile = resolve(profile);
- const host = await videoCliDistribution.openRuntimeHost(resolvedProfile, {
- packageRoot,
- ...(distributionPackageRoot === undefined ? {} : { distributionPackageRoot }),
- });
- const runtime = await host.openArchive({ readOnly: true });
- const artifacts = await host.openArtifacts();
+ const resolvedProfile = profile === undefined ? undefined : resolve(profile);
+ const host = resolvedProfile === undefined
+ ? undefined
+ : await videoCliDistribution.openRuntimeHost(resolvedProfile, {
+ packageRoot,
+ ...(distributionPackageRoot === undefined ? {} : { distributionPackageRoot }),
+ });
+ const runtime = await host?.openArchive({ readOnly: true });
+ const defaultResultRoot = join(workspaceRoot, ".hypit", "results");
+ const openedResults = host?.openResults === undefined
+ ? undefined
+ : await host.openResults(defaultResultRoot);
+ const results = openedResults?.repository ?? new FileBuildResultRepository(defaultResultRoot);
return {
- profile: resolvedProfile,
- runtime,
+ ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),
+ ...(runtime === undefined ? {} : { runtime }),
async library() {
- return await readStudioLibrary({ profile: resolvedProfile, workspaceRoot, runtime });
+ return await readStudioLibrary({
+ ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),
+ workspaceRoot,
+ ...(runtime === undefined ? {} : { runtime }),
+ results,
+ });
},
async resolveBuildRecord(build, output) {
- const held = await runtime.status(build);
- const state = held.build?.state;
- if (state === undefined) return undefined;
- const alias = held.catalog?.aliases.find((item) => item.name === output);
- if (alias !== undefined && alias.ref.kind !== "logical-output") {
- throw new Error(`Build ${build} alias ${output} is an authored Record, not a Logical Output`);
+ return await resolveBuildResultRecord(results, build, output);
+ },
+ async openArtifact(build, output, valuePath) {
+ const resolved = await results.resolve(build, output);
+ if (resolved === undefined) return undefined;
+ const match = filesInResolvedOutput(resolved).find((item) => item.valuePath === valuePath);
+ if (match === undefined) return undefined;
+ const stream = await results.openFile(resolved.build, match.file);
+ if (stream === undefined) return undefined;
+ const chunks: Uint8Array[] = [];
+ let size = 0;
+ for await (const chunk of stream) {
+ const copy = Uint8Array.from(chunk);
+ chunks.push(copy);
+ size += copy.byteLength;
+ }
+ const bytes = new Uint8Array(size);
+ let offset = 0;
+ for (const chunk of chunks) {
+ bytes.set(chunk, offset);
+ offset += chunk.byteLength;
}
- const record = alias === undefined
- ? selectArchivedRecord(state, { output })
- : selectArchivedRecord(state, {
- name: output,
- catalog: held.catalog as NonNullable<typeof held.catalog>,
- });
- return { type: record.type, value: record.value };
+ return { mediaType: match.file.mediaType, bytes };
},
- async read(digest) { return await artifacts.readArtifact(digest) ?? undefined; },
async close() {
- await artifacts.close();
- await runtime.close();
+ await openedResults?.close();
+ await runtime?.close();
},
};
}
diff --git a/packages/studio/src/compile.ts b/packages/studio/src/compile.ts
index d8292a58..b4532be9 100644
--- a/packages/studio/src/compile.ts
+++ b/packages/studio/src/compile.ts
@@ -35,7 +35,7 @@ export async function observedCompiledSource(
): Promise<CompiledSource> {
const served = new Map<string, ServedFile>();
for (const attachment of compiled.attachments) {
- served.set(attachment.artifact.digest, {
+ served.set(attachment.artifact.resource, {
mediaType: attachment.artifact.mediaType,
bytes: await bytesOf(attachment),
});
diff --git a/packages/studio/src/execute.ts b/packages/studio/src/execute.ts
index dbe7a854..3962e9a0 100644
--- a/packages/studio/src/execute.ts
+++ b/packages/studio/src/execute.ts
@@ -1,5 +1,5 @@
-import { EndpointRegistry, MemoryArtifactStore, NodeDriver } from "@hypit/driver-node";
-import type { ArtifactStore } from "@hypit/runtime";
+import { EndpointRegistry, MemoryResourceStore, NodeDriver } from "@hypit/driver-node";
+import type { ResourceStore } from "@hypit/runtime";
import type { BuildState } from "@hypit/protocol";
import type { StudioDomain } from "./domain.js";
@@ -15,14 +15,14 @@ export type Executed = {
export async function executeDeterministic(
domain: StudioDomain,
planned: BuildState,
- artifacts: ArtifactStore,
+ resources: ResourceStore,
endpoints: EndpointRegistry = new EndpointRegistry(),
): Promise<Executed> {
const result = await new NodeDriver({
producers: domain.producers,
validators: domain.validators,
endpoints,
- artifacts,
+ resources,
}).run(planned);
const counts = new Map<string, number>();
for (const item of result.blocked) {
@@ -40,4 +40,4 @@ export async function executeDeterministic(
};
}
-export { MemoryArtifactStore };
+export { MemoryResourceStore };
diff --git a/packages/studio/src/fallback-companions.ts b/packages/studio/src/fallback-companions.ts
index 4834b325..71170612 100644
--- a/packages/studio/src/fallback-companions.ts
+++ b/packages/studio/src/fallback-companions.ts
@@ -9,7 +9,7 @@ type TerminalVisualTrack = {
readonly subjectId?: string;
readonly elements?: readonly {
readonly kind?: string;
- readonly artifact?: { readonly digest?: string };
+ readonly artifact?: { readonly resource?: string };
}[];
}[];
};
@@ -18,7 +18,7 @@ type TerminalAudioTrack = {
readonly clips?: readonly {
readonly id: string;
readonly subjectId?: string;
- readonly artifact?: { readonly digest?: string };
+ readonly artifact?: { readonly resource?: string };
}[];
};
@@ -44,14 +44,14 @@ function projectTerminalVisual(context: StudioTrackCompanionContext): readonly S
return context.generic().map((entity) => {
const present = entity.presentId === undefined ? undefined : presents.get(entity.presentId);
const material = present?.elements?.find((element) =>
- (element.kind === "image" || element.kind === "video") && element.artifact?.digest !== undefined);
- const digest = material?.artifact?.digest;
+ (element.kind === "image" || element.kind === "video") && element.artifact?.resource !== undefined);
+ const resource = material?.artifact?.resource;
return withTemporalLineage(context, {
...entity,
...(present?.subjectId === undefined ? {} : { authoredId: present.subjectId }),
display: {
title: present?.subjectId ?? entity.display.title,
- layers: digest === undefined ? [] : [previewLayer(artifactPreview(material?.kind === "image" ? "image" : "video", digest), material?.kind === "image" ? "repeat-x" : "storyboard")],
+ layers: resource === undefined ? [] : [previewLayer(artifactPreview(material?.kind === "image" ? "image" : "video", resource), material?.kind === "image" ? "repeat-x" : "storyboard")],
},
presentation: { entity: "media-item", chrome: "standard" },
});
@@ -63,13 +63,13 @@ function projectTerminalAudio(context: StudioTrackCompanionContext): readonly St
.map((clip) => [clip.id, clip] as const));
return context.generic().map((entity, index) => {
const clip = clips.get(context.spans[index]?.id ?? "");
- const digest = clip?.artifact?.digest;
+ const resource = clip?.artifact?.resource;
return withTemporalLineage(context, {
...entity,
...(clip?.subjectId === undefined ? {} : { authoredId: clip.subjectId }),
display: {
title: clip?.subjectId ?? entity.display.title,
- layers: digest === undefined ? [] : [previewLayer(artifactPreview("audio", digest), "waveform")],
+ layers: resource === undefined ? [] : [previewLayer(artifactPreview("audio", resource), "waveform")],
},
presentation: { entity: "audio-clip", chrome: "standard" },
});
diff --git a/packages/studio/src/preview/render.ts b/packages/studio/src/preview/render.ts
index 38b1ddd0..8f0f7df3 100644
--- a/packages/studio/src/preview/render.ts
+++ b/packages/studio/src/preview/render.ts
@@ -7,7 +7,7 @@ import { injectRuntimeShim } from "./runtime-shim.js";
export type RenderInput = {
readonly composition: Composition;
readonly space: ProgramSpace;
- /** Digests Studio can serve for material selected by the Run. */
+ /** Resources Studio can serve for material selected by the Run. */
readonly served?: ReadonlySet<string>;
};
@@ -24,20 +24,20 @@ export function renderPreview(input: RenderInput): string {
// The only Artifacts a preview can reference are files the author already
// has. Anything else would be a Provider's output, which does not exist yet,
// and failing loudly beats serving a picture with holes in it.
- if (input.served?.has(artifact.digest) !== true) {
- throw new Error(`Preview composition references Artifact ${artifact.digest}, which it cannot serve.`);
+ if (input.served?.has(artifact.resource) !== true) {
+ throw new Error(`Preview composition references Artifact ${artifact.resource}, which it cannot serve.`);
}
- return `/__studio/material/${artifact.digest}`;
+ return `/__studio/material/${artifact.resource}`;
});
const audio = input.composition.tracks
.filter((track): track is AudioTrack => track.kind === "audio")
.flatMap((track) => track.clips)
.map((clip) => {
- if (input.served?.has(clip.artifact.digest) !== true) {
- throw new Error(`Preview audio references Artifact ${clip.artifact.digest}, which it cannot serve.`);
+ if (input.served?.has(clip.artifact.resource) !== true) {
+ throw new Error(`Preview audio references Artifact ${clip.artifact.resource}, which it cannot serve.`);
}
return `<audio class="hypit-studio-audio" preload="auto"
- src="/__studio/material/${clip.artifact.digest}"
+ src="/__studio/material/${clip.artifact.resource}"
data-start="${clip.target.startSample / 48_000}"
data-duration="${(clip.target.endSampleExclusive - clip.target.startSample) / 48_000}"
data-media-start="${clip.source.startSample / 48_000}"
diff --git a/packages/studio/src/programme.ts b/packages/studio/src/programme.ts
index 1c3cd3d9..21b79bd8 100644
--- a/packages/studio/src/programme.ts
+++ b/packages/studio/src/programme.ts
@@ -1,5 +1,5 @@
import type { ArtifactAttachment } from "@hypit/workspace";
-import type { BlobRef, Digest, StoredValue } from "@hypit/protocol";
+import type { BlobRef, ResourceId, StoredValue } from "@hypit/protocol";
import { sameType } from "@hypit/protocol";
import type { Composition } from "@hypit/composition";
import { compositionTypes } from "@hypit/composition";
@@ -16,7 +16,7 @@ import type { StudioResolvedTrack, StudioTemporalBinding } from "@hypit/studio-a
import type { StudioArchive } from "./archive.js";
import type { CompiledSource, ServedFile } from "./compile.js";
import type { StudioDomain } from "./domain.js";
-import { executeDeterministic, MemoryArtifactStore } from "./execute.js";
+import { executeDeterministic, MemoryResourceStore } from "./execute.js";
import type { EndpointRegistry } from "@hypit/driver-node";
import type { RunPlan } from "./run.js";
import type { StudioViewRequirement } from "./studio-preflight.js";
@@ -85,12 +85,12 @@ function selectedValue(
}
function compositionArtifacts(composition: Composition): readonly BlobRef[] {
- const found = new Map<Digest, BlobRef>();
+ const found = new Map<ResourceId, BlobRef>();
const visit = (value: unknown): void => {
if (value === null || typeof value !== "object") return;
if ((value as { readonly kind?: unknown }).kind === "blob") {
const artifact = value as BlobRef;
- found.set(artifact.digest, artifact);
+ found.set(artifact.resource, artifact);
return;
}
if (Array.isArray(value)) {
@@ -120,38 +120,38 @@ export async function preview(input: {
const found = exportsByRef.get(ref);
return found === undefined ? [] : [found];
});
- const store = new MemoryArtifactStore();
+ const store = new MemoryResourceStore();
const served = new Map(input.source.served);
for (const attachment of input.run.attachments) {
const bytes = await bytesOf(attachment);
- await store.put(bytes, attachment.artifact.mediaType);
- served.set(attachment.artifact.digest, {
+ await store.write(attachment.artifact, bytes);
+ served.set(attachment.artifact.resource, {
mediaType: attachment.artifact.mediaType,
bytes,
});
}
- for (const [, file] of input.source.served) await store.put(file.bytes, file.mediaType);
- const artifacts = {
- async get(digest: Digest) {
- const local = await store.get(digest);
- if (local !== undefined) return local;
- const archived = await input.archive?.read(digest);
- if (archived !== undefined) {
- served.set(digest, { mediaType: "application/octet-stream", bytes: archived });
- }
- return archived;
+ for (const [resource, file] of input.source.served) {
+ await store.write({ kind: "blob", resource: resource as ResourceId, size: file.bytes.byteLength, mediaType: file.mediaType }, file.bytes);
+ }
+ const resources = {
+ async get(resource: ResourceId) {
+ return await store.get(resource);
},
async put(bytes: Uint8Array, mediaType: string) {
const ref = await store.put(bytes, mediaType);
- served.set(ref.digest, { mediaType, bytes });
+ served.set(ref.resource, { mediaType, bytes });
return ref;
},
- async has(digest: Digest) {
- return await store.has(digest) || await input.archive?.read(digest) !== undefined;
+ async write(resource: BlobRef, bytes: Uint8Array) {
+ await store.write(resource, bytes);
+ served.set(resource.resource, { mediaType: resource.mediaType, bytes });
+ },
+ async has(resource: ResourceId) {
+ return await store.has(resource);
},
};
const planned = input.run.plan(input.run.run, targets.map((target) => target.ref));
- const executed = await executeDeterministic(input.domain, planned.state, artifacts, input.endpoints);
+ const executed = await executeDeterministic(input.domain, planned.state, resources, input.endpoints);
if (executed.unserved.length > 0) {
throw new Error(
`Studio projection is unresolved: ${executed.unserved.map((item) => item.capability).join(", ")}`,
@@ -180,9 +180,9 @@ export async function preview(input: {
}
const composition = compositionValue.value as unknown as Composition;
for (const artifact of compositionArtifacts(composition)) {
- if (served.has(artifact.digest)) continue;
- const bytes = await input.archive?.read(artifact.digest);
- if (bytes !== undefined) served.set(artifact.digest, { mediaType: artifact.mediaType, bytes });
+ if (!served.has(artifact.resource)) {
+ throw new Error(`Studio composition Resource ${artifact.resource} has no Run attachment.`);
+ }
}
const projectionByRef = new Map(input.projections.map((projection) => [projection.ref, projection]));
const tracks: BuiltTrack[] = targets.flatMap((target) => {
diff --git a/packages/studio/src/server.ts b/packages/studio/src/server.ts
index 49a6b9f4..5c47beb9 100644
--- a/packages/studio/src/server.ts
+++ b/packages/studio/src/server.ts
@@ -589,20 +589,20 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
});
return;
}
- const storyboardDigest = /^\/__studio\/storyboard\/(sha256:[a-f0-9]{64})$/u.exec(url.pathname)?.[1];
- if (storyboardDigest !== undefined) {
+ const storyboardResource = /^\/__studio\/storyboard\/(res_[a-zA-Z0-9._:-]+)$/u.exec(url.pathname)?.[1];
+ if (storyboardResource !== undefined) {
void (async () => {
- const file = material.get(storyboardDigest);
+ const file = material.get(storyboardResource);
if (file === undefined || !file.mediaType.startsWith("video/")) {
response.statusCode = 404;
response.end();
return;
}
try {
- let pending = storyboards.get(storyboardDigest);
+ let pending = storyboards.get(storyboardResource);
if (pending === undefined) {
pending = createStudioStoryboard(file);
- storyboards.set(storyboardDigest, pending);
+ storyboards.set(storyboardResource, pending);
}
const storyboard = await pending;
response.statusCode = 200;
@@ -617,15 +617,15 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
if (request.method === "HEAD") response.end();
else response.end(Buffer.from(storyboard.bytes));
} catch (error) {
- storyboards.delete(storyboardDigest);
+ storyboards.delete(storyboardResource);
json(response, 500, { error: error instanceof Error ? error.message : String(error) });
}
})();
return;
}
- const digest = /^\/__studio\/material\/(sha256:[a-f0-9]{64})$/u.exec(url.pathname)?.[1];
- if (digest !== undefined) {
- const file = material.get(digest);
+ const materialResource = /^\/__studio\/material\/(res_[a-zA-Z0-9._:-]+)$/u.exec(url.pathname)?.[1];
+ if (materialResource !== undefined) {
+ const file = material.get(materialResource);
if (file === undefined) {
response.statusCode = 404;
response.end();
@@ -639,28 +639,28 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
else response.end(Buffer.from(file.bytes));
return;
}
- const artifactDigest = /^\/__studio\/artifact\/(sha256:[a-f0-9]{64})$/u.exec(url.pathname)?.[1];
- if (artifactDigest !== undefined) {
+ if (url.pathname === "/__studio/artifact") {
void (async () => {
- const view = library ?? await readLibrary();
- const artifact = view.artifacts.find((item) => item.digest === artifactDigest);
- if (artifact === undefined || options.archive === undefined) {
+ const build = url.searchParams.get("build");
+ const output = url.searchParams.get("output");
+ const valuePath = url.searchParams.get("path");
+ if (build === null || output === null || valuePath === null || options.archive === undefined) {
response.statusCode = 404;
response.end();
return;
}
- const bytes = await options.archive.read(artifactDigest as import("@hypit/protocol").Digest);
- if (bytes === undefined) {
+ const artifact = await options.archive.openArtifact(build, output, valuePath);
+ if (artifact === undefined) {
response.statusCode = 404;
response.end();
return;
}
response.statusCode = 200;
response.setHeader("content-type", artifact.mediaType);
- response.setHeader("content-length", String(bytes.byteLength));
- response.setHeader("cache-control", "private, max-age=31536000, immutable");
+ response.setHeader("content-length", String(artifact.bytes.byteLength));
+ response.setHeader("cache-control", "private, no-store");
if (request.method === "HEAD") response.end();
- else response.end(Buffer.from(bytes));
+ else response.end(Buffer.from(artifact.bytes));
})().catch((error) => {
json(response, 500, { error: error instanceof Error ? error.message : String(error) });
});
diff --git a/packages/studio/src/shared.ts b/packages/studio/src/shared.ts
index a212d87f..4d82679c 100644
--- a/packages/studio/src/shared.ts
+++ b/packages/studio/src/shared.ts
@@ -203,16 +203,17 @@ export type StudioTaskView = {
};
export type StudioArtifactView = {
- /** Build-qualified identity. The same digest in two Builds remains two historical results. */
+ /** Build-qualified identity derived from the public Output and its value path. */
readonly id: string;
readonly build: string;
readonly createdAt: number;
- readonly digest: string;
+ readonly output: string;
+ readonly valuePath: string;
+ readonly ownerBuild: string;
+ readonly ownerOutput: string;
+ readonly filePath: string;
readonly size: number;
readonly mediaType: string;
- readonly records: readonly string[];
- readonly outputs: readonly string[];
- readonly paths: readonly string[];
readonly source: string;
readonly run?: string;
};
diff --git a/packages/studio/src/studio-registry.ts b/packages/studio/src/studio-registry.ts
index bce3b0f5..3039efd0 100644
--- a/packages/studio/src/studio-registry.ts
+++ b/packages/studio/src/studio-registry.ts
@@ -113,7 +113,7 @@ function validateDraftVocabulary(companion: StudioTrackCompanion, draft: StudioE
}
const source = layer.preview.source;
if (source.kind === "artifact") {
- if (typeof source.digest !== "string" || source.digest.length === 0) {
+ if (typeof source.resource !== "string" || source.resource.length === 0) {
throw new Error(`Studio Track Companion ${companion.id} entity ${draft.id} has invalid Artifact source`);
}
} else if (source.kind !== "surface-preview"
diff --git a/packages/studio/src/ui/library.ts b/packages/studio/src/ui/library.ts
index 0ad8195e..ca2d83dc 100644
--- a/packages/studio/src/ui/library.ts
+++ b/packages/studio/src/ui/library.ts
@@ -104,10 +104,15 @@ function artifactCard(artifact: StudioArtifactView): HTMLElement {
const kind = artifactKind(artifact.mediaType);
const link = document.createElement("a");
link.className = `artifact-card artifact-${kind.label.toLowerCase()}`;
- link.href = `/__studio/artifact/${artifact.digest}`;
+ const query = new URLSearchParams({
+ build: artifact.build,
+ output: artifact.output,
+ path: artifact.valuePath,
+ });
+ link.href = `/__studio/artifact?${query.toString()}`;
link.target = "_blank";
link.rel = "noreferrer";
- const title = artifact.outputs[0] ?? artifact.records[0] ?? kind.label;
+ const title = artifact.valuePath === "$" ? artifact.output : `${artifact.output} ${artifact.valuePath}`;
link.innerHTML = `
<div class="artifact-preview">
<span class="artifact-glyph">${icon(kind.icon)}</span>
@@ -127,7 +132,12 @@ function artifactCard(artifact: StudioArtifactView): HTMLElement {
image.loading = "lazy";
link.querySelector<HTMLElement>(".artifact-preview")!.prepend(image);
}
- link.title = [title, artifact.mediaType, artifact.digest, artifact.run ?? artifact.source].join("\n");
+ link.title = [
+ title,
+ artifact.mediaType,
+ `${artifact.ownerBuild}/${artifact.ownerOutput}/${artifact.filePath}`,
+ artifact.run ?? artifact.source,
+ ].join("\n");
return link;
}
@@ -237,7 +247,7 @@ export function createLibraryPane(code: CodePane): LibraryPane {
const renderArtifacts = (): void => {
const artifacts = library?.artifacts ?? [];
- element.querySelector<HTMLElement>("[data-artifact-count]")!.textContent = `${artifacts.length} stored object${artifacts.length === 1 ? "" : "s"}`;
+ element.querySelector<HTMLElement>("[data-artifact-count]")!.textContent = `${artifacts.length} public file${artifacts.length === 1 ? "" : "s"}`;
const filters = [
["all", "All"],
["video", "Video"],
@@ -258,9 +268,7 @@ export function createLibraryPane(code: CodePane): LibraryPane {
if (shown.length === 0) {
artifactGrid.replaceChildren(emptyState("archive",
artifacts.length === 0 ? "No accepted artifacts" : `No ${artifactFilter} artifacts`,
- library?.runtime === undefined
- ? "Artifacts appear only from a selected Runtime archive."
- : "Only ArtifactStore objects referenced by accepted Records appear here."));
+ "Public files appear here when a Build Result contains them."));
return;
}
artifactGrid.replaceChildren(...shown.map(artifactCard));
@@ -297,7 +305,7 @@ export function createLibraryPane(code: CodePane): LibraryPane {
} catch (error) {
const detail = error instanceof Error ? error.message : String(error);
if (active === "tasks") taskList.replaceChildren(emptyState("tasks", "Archive unavailable", detail));
- if (active === "artifacts") artifactGrid.replaceChildren(emptyState("archive", "ArtifactStore unavailable", detail));
+ if (active === "artifacts") artifactGrid.replaceChildren(emptyState("archive", "Build Results unavailable", detail));
} finally {
refreshing = false;
element.classList.remove("is-refreshing");
diff --git a/packages/studio/src/ui/material-preview.ts b/packages/studio/src/ui/material-preview.ts
index f5cb8df5..864b2b99 100644
--- a/packages/studio/src/ui/material-preview.ts
+++ b/packages/studio/src/ui/material-preview.ts
@@ -15,7 +15,7 @@ const storyboards = new Map<string, Promise<Storyboard | undefined>>();
const resolvedStoryboards = new Map<string, Storyboard | undefined>();
function previewUrl(preview: StudioMaterialPreview): string {
- if (preview.source.kind === "artifact") return `/__studio/material/${preview.source.digest}`;
+ if (preview.source.kind === "artifact") return `/__studio/material/${preview.source.resource}`;
const query = new URLSearchParams({
module: preview.source.module,
version: preview.source.version,
diff --git a/packages/studio/test/archive.test.ts b/packages/studio/test/archive.test.ts
index 9e3267cf..87b8cdfe 100644
--- a/packages/studio/test/archive.test.ts
+++ b/packages/studio/test/archive.test.ts
@@ -1,13 +1,17 @@
import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
import test from "node:test";
-import type { BuildState, Digest } from "@hypit/protocol";
+import type { BuildState, ResourceId } from "@hypit/protocol";
+import type { BuildResultRepository } from "@hypit/build-result";
import type { BuildCatalogEntry } from "@hypit/runtime";
import type { RuntimeHostStatus } from "@hypit/runtime-host-node";
-import { readStudioLibrary } from "../src/archive.js";
+import { openStudioArchive, readStudioLibrary } from "../src/archive.js";
-const digest = `sha256:${"a".repeat(64)}` as Digest;
+const resource = "res_studio-archive" as ResourceId;
function state(): BuildState {
return {
@@ -25,7 +29,7 @@ function state(): BuildState {
records: [{
id: "final-record",
type: { module: { name: "example", version: "1" }, name: "Video" },
- value: { kind: "blob", digest, size: 42, mediaType: "video/mp4" },
+ value: { kind: "blob", resource, size: 42, mediaType: "video/mp4" },
}],
steps: [],
needs: [],
@@ -44,7 +48,7 @@ function catalog(build: string, root: string): BuildCatalogEntry {
};
}
-test("Studio library shows only this environment's archived Builds and accepted Artifacts", async () => {
+test("Studio library joins this environment's Builds with project Build Result files", async () => {
const relevant = catalog("build-inside", "/project");
const unrelated = catalog("build-outside", "/another-project");
const status: RuntimeHostStatus = {
@@ -60,6 +64,35 @@ test("Studio library shows only this environment's archived Builds and accepted
terminal: "complete",
},
};
+ const manifests = [relevant, unrelated].map((entry) => ({
+ format: "hypit.build-result@1" as const,
+ id: entry.build,
+ source: entry.source,
+ ...(entry.run === undefined ? {} : { run: entry.run }),
+ targets: ["final.video"],
+ startedAt: entry.createdAt,
+ updatedAt: entry.createdAt,
+ finishedAt: entry.createdAt,
+ status: "complete" as const,
+ outputs: {
+ "final.video": {
+ type: { module: { name: "example", version: "1" }, name: "Video" },
+ value: { kind: "build-file" as const, path: "files/final.video.mp4", size: 42, mediaType: "video/mp4" },
+ },
+ },
+ }));
+ const results: BuildResultRepository = {
+ async create() { throw new Error("not used"); },
+ async openWriter() { return undefined; },
+ async read(build) { return manifests.find((item) => item.id === build); },
+ async list() { return manifests; },
+ async resolve(build, output) {
+ const manifest = manifests.find((item) => item.id === build);
+ const value = manifest?.outputs[output as "final.video"];
+ return value === undefined ? undefined : { build, output, type: value.type, value: value.value };
+ },
+ async openFile() { return undefined; },
+ };
const view = await readStudioLibrary({
profile: "/project/hypit.runtime.json",
workspaceRoot: "/project",
@@ -70,6 +103,7 @@ test("Studio library shows only this environment's archived Builds and accepted
return status;
},
},
+ results,
});
assert.deepEqual(view.tasks.map((task) => ({
@@ -87,13 +121,58 @@ test("Studio library shows only this environment's archived Builds and accepted
}]);
assert.deepEqual(view.artifacts.map((artifact) => ({
build: artifact.build,
- digest: artifact.digest,
+ output: artifact.output,
+ valuePath: artifact.valuePath,
+ filePath: artifact.filePath,
mediaType: artifact.mediaType,
- outputs: artifact.outputs,
})), [{
build: "build-inside",
- digest,
+ output: "final.video",
+ valuePath: "$",
+ filePath: "files/final.video.mp4",
mediaType: "video/mp4",
- outputs: ["final.video"],
}]);
});
+
+test("Studio opens project Build Results without a Runtime or ResourceStore", async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-studio-results-"));
+ const directory = join(root, ".hypit", "results", "build-one");
+ const bytes = new TextEncoder().encode("finished-video");
+ try {
+ await mkdir(join(directory, "files"), { recursive: true });
+ await writeFile(join(directory, "files", "final.mp4"), bytes);
+ await writeFile(join(directory, "result.json"), `${JSON.stringify({
+ format: "hypit.build-result@1",
+ id: "build-one",
+ name: "First cut",
+ source: { path: join(root, "main.svml") },
+ run: { path: join(root, "build.svrun") },
+ targets: ["final.video"],
+ startedAt: 100,
+ updatedAt: 200,
+ finishedAt: 200,
+ status: "complete",
+ outputs: {
+ "final.video": {
+ type: { module: { name: "example", version: "1" }, name: "Video" },
+ value: { kind: "build-file", path: "files/final.mp4", size: bytes.byteLength, mediaType: "video/mp4" },
+ },
+ },
+ }, null, 2)}\n`, "utf8");
+
+ const archive = await openStudioArchive(undefined, root, root);
+ assert(archive !== undefined);
+ const view = await archive.library();
+ assert.equal(view.runtime, undefined);
+ assert.deepEqual(view.artifacts.map((item) => [item.build, item.output, item.valuePath]), [
+ ["build-one", "final.video", "$"],
+ ]);
+ assert.deepEqual((await archive.openArtifact("build-one", "final.video", "$"))?.bytes, bytes);
+ const record = await archive.resolveBuildRecord("build-one", "final.video");
+ assert.equal(record?.value.kind, "blob");
+ assert.equal(record?.attachments?.length, 1);
+ await archive.close();
+ } finally {
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/packages/transport-aws-lambda/README.md b/packages/transport-aws-lambda/README.md
index dd6bd648..0f6a8d2f 100644
--- a/packages/transport-aws-lambda/README.md
+++ b/packages/transport-aws-lambda/README.md
@@ -17,4 +17,4 @@ misleading. An Endpoint may invoke a coordinator Lambda synchronously; that coor
long work and return a checkpoint which the Endpoint later polls through another synchronous call.
AWS authentication uses the SDK credential chain or an injected trusted client. Large media belongs
-in ArtifactStore; JSON payloads are bounded by Lambda's synchronous payload limit.
+in ResourceStore; JSON payloads are bounded by Lambda's synchronous payload limit.
diff --git a/packages/typography-track/src/program.ts b/packages/typography-track/src/program.ts
index ae6e300b..bc77e22e 100644
--- a/packages/typography-track/src/program.ts
+++ b/packages/typography-track/src/program.ts
@@ -77,7 +77,7 @@ export function assertTextStyle(style: TextStyle): void {
throw new Error("TextStyle typography size or weight is invalid.");
}
if (style.typography.fonts === undefined) {
- throw new Error("Official TextStyle requires an exact content-addressed font stack.");
+ throw new Error("Official TextStyle requires an exact declared font stack.");
}
if (!["start", "center", "end"].includes(style.point.anchorInline)
|| !["start", "center", "end"].includes(style.point.anchorBlock)
@@ -483,7 +483,7 @@ function maskTextElement(item: TextItem): VisualTextElement {
throw new Error(`${item.id} advanced Text Mask flow must be materialized by an independent package.`);
}
const fonts = typography.fonts;
- if (fonts.length === 0) throw new Error("Text Mask requires an exact content-addressed font stack.");
+ if (fonts.length === 0) throw new Error("Text Mask requires an exact declared font stack.");
if (fonts !== undefined) {
const primary = fonts[0];
if (primary === undefined || primary.weight !== typography.weight || primary.style !== typography.style || typography.synthesis !== "none") {
diff --git a/packages/typography-track/test/typography-track.test.ts b/packages/typography-track/test/typography-track.test.ts
index 80e2fdd0..18e7ff21 100644
--- a/packages/typography-track/test/typography-track.test.ts
+++ b/packages/typography-track/test/typography-track.test.ts
@@ -1,6 +1,6 @@
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
import { semanticTrackFixture } from "../../../test/semantic-track-fixture.js";
import { projectSelectionWindow } from "../../../test/temporal-fixture.js";
@@ -61,7 +61,7 @@ const semantic = semanticTrackFixture(space, { anchors: [
const exactTestFont: FontArtifactRef = {
sources: [{ artifact: {
kind: "blob",
- digest: fixtureDigest("typography-track-test-font"),
+ resource: fixtureResource("typography-track-test-font"),
size: 1,
mediaType: "font/woff2",
} }],
@@ -72,7 +72,7 @@ const exactTestFont: FontArtifactRef = {
const exactTestSurface: CompositableSurfaceRef = {
artifact: {
kind: "blob",
- digest: fixtureDigest("typography-track-test-surface"),
+ resource: fixtureResource("typography-track-test-surface"),
size: 1,
mediaType: "image/png",
},
@@ -225,7 +225,7 @@ test("Text Mask explicitly consumes one authored Text Program and one owned stil
}],
});
const material: CompositableSurfaceRef = {
- artifact: { kind: "blob", digest: fixtureDigest("text-mask-material"), size: 1, mediaType: "image/png" },
+ artifact: { kind: "blob", resource: fixtureResource("text-mask-material"), size: 1, mediaType: "image/png" },
width: 800, height: 240, colorSpace: "srgb", alphaMode: "straight", timing: { kind: "still" },
};
const track = renderTextMaskTrack(space, program, material, sealTextMaskSpec({
diff --git a/packages/video-cli/src/picture.ts b/packages/video-cli/src/picture.ts
index 0d06bd20..b9a4acc9 100644
--- a/packages/video-cli/src/picture.ts
+++ b/packages/video-cli/src/picture.ts
@@ -1,7 +1,7 @@
import type { CliPicture, CliPictureRequest } from "@hypit/cli";
import { EnvironmentCredentialStore } from "@hypit/credential-store-env";
import { OsCredentialStore } from "@hypit/credential-store-os";
-import { EndpointRegistry, MemoryArtifactStore } from "@hypit/driver-node";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
import type { EndpointRegistration } from "@hypit/driver-node";
import type { EndpointOutcome } from "@hypit/endpoint-kit";
import { sealGenerationPortRequest, verifyGeneratedImageSet } from "@hypit/generation";
@@ -121,15 +121,15 @@ function delay(milliseconds: number): Promise<void> {
/** Read the single picture out of the completed generation, then out of the Store. */
async function readPicture(
outcome: Extract<EndpointOutcome, { readonly status: "completed" }>,
- artifacts: MemoryArtifactStore,
+ resources: MemoryResourceStore,
): Promise<{ readonly bytes: Uint8Array; readonly mediaType: string }> {
const value = outcome.result.value;
assert(value.kind === "inline", "the model returned no inline image set");
verifyGeneratedImageSet(value.value);
const [image] = (value.value as unknown as { readonly images: readonly BlobRef[] }).images;
assert(image !== undefined, "the model returned no picture");
- const bytes = await artifacts.get(image.digest);
- assert(bytes !== undefined, `generated Artifact ${image.digest} was not stored`);
+ const bytes = await resources.get(image.resource);
+ assert(bytes !== undefined, `generated Artifact ${image.resource} was not stored`);
return { bytes, mediaType: image.mediaType };
}
@@ -137,7 +137,7 @@ async function readPicture(
* Generate one picture with no Core graph.
*
* A package asset is authoring input, so nothing here is durable: the Need, the
- * ArtifactStore and the Provider all live for the length of this one call, and no
+ * ResourceStore and the Provider all live for the length of this one call, and no
* Build, Record or Runtime Profile observes any of it.
*/
export async function generateVideoCliPicture(request: CliPictureRequest): Promise<CliPicture> {
@@ -158,11 +158,11 @@ export async function generateVideoCliPicture(request: CliPictureRequest): Promi
const registration = resolution.registration;
assert(registration.kind === "asynchronous",
`${model.ports.model} is fulfilled by an Endpoint hypit image cannot drive`);
- const artifacts = new MemoryArtifactStore();
+ const resources = new MemoryResourceStore();
const common = {
command: { kind: "fulfill-need" as const, id: "command:hypit-image", need },
need,
- artifacts,
+ resources,
credentials: await resolveCredentials(registration),
operation: "operation:hypit-image",
};
@@ -175,7 +175,7 @@ export async function generateVideoCliPicture(request: CliPictureRequest): Promi
assert(outcome.status === "completed", outcome.status === "failed"
? `${model.ports.model} failed: ${outcome.failure.code} — ${outcome.failure.message}`
: `${model.ports.model} returned no picture`);
- const picture = await readPicture(outcome, artifacts);
+ const picture = await readPicture(outcome, resources);
return {
package: specifier,
model: model.ports.model,
diff --git a/packages/video-cli/test/cli.test.ts b/packages/video-cli/test/cli.test.ts
index afadace3..e146a509 100644
--- a/packages/video-cli/test/cli.test.ts
+++ b/packages/video-cli/test/cli.test.ts
@@ -1,5 +1,4 @@
import assert from "node:assert/strict";
-import { createHash } from "node:crypto";
import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
@@ -136,21 +135,21 @@ test("materializeRecord copies an archived Artifact without rerunning a Build",
const root = await mkdtemp(join(tmpdir(), "hypit-cli-get-"));
try {
const bytes = Buffer.from("final-video-bytes");
- const artifactDigest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+ const artifactResource = "res_archived-final-video";
const output = join(root, "final.mp4");
const runtime = {
- async openArtifact(digest: string) {
- return digest === artifactDigest ? (async function* () { yield bytes; })() : undefined;
+ async openResource(resource: string) {
+ return resource === artifactResource ? (async function* () { yield bytes; })() : undefined;
},
} as Parameters<typeof materializeRecord>[0];
const record = {
id: "final.video",
- value: { kind: "inline", value: { digest: artifactDigest, size: bytes.byteLength, mediaType: "video/mp4" } },
+ value: { kind: "inline", value: { resource: artifactResource, size: bytes.byteLength, mediaType: "video/mp4" } },
} as unknown as Parameters<typeof materializeRecord>[1];
const result = await materializeRecord(runtime, record, output);
assert.deepEqual(result, {
kind: "artifact",
- digest: artifactDigest,
+ resource: artifactResource,
mediaType: "video/mp4",
size: bytes.byteLength,
path: output,
diff --git a/packages/whisperx/test/whisperx.test.ts b/packages/whisperx/test/whisperx.test.ts
index 61be9aee..bcf2839d 100644
--- a/packages/whisperx/test/whisperx.test.ts
+++ b/packages/whisperx/test/whisperx.test.ts
@@ -6,9 +6,9 @@ import { sealSpeechEvidenceAudio } from "@hypit/speech";
import type { SpeechEvidenceAudio } from "@hypit/speech";
import assert from "node:assert/strict";
import test from "node:test";
-import { fixtureDigest } from "../../../test/fixture-digest.js";
+import { fixtureResource } from "../../../test/fixture-resource.js";
-import type { Digest, ProducerRef } from "@hypit/protocol";
+import type { ResourceId, ProducerRef } from "@hypit/protocol";
import {
whisperXComponent,
whisperXProducers,
@@ -19,7 +19,7 @@ function evidenceAudio(): SpeechEvidenceAudio {
return sealSpeechEvidenceAudio({
artifact: {
kind: "blob",
- digest: fixtureDigest("whisperx-test:evidence-audio"),
+ resource: fixtureResource("whisperx-test:evidence-audio"),
size: 32_044,
mediaType: "audio/wav",
},
@@ -30,7 +30,7 @@ function evidenceAudio(): SpeechEvidenceAudio {
test("WhisperX receives normalized bytes without authored Segment truth", () => {
const valid = evidenceAudio();
const request = whisperXRequestForEvidenceAudio(valid, { language: "es" });
- assert.equal(request.audio.digest, valid.artifact.digest);
+ assert.equal(request.audio.resource, valid.artifact.resource);
assert.equal("segments" in request, false);
assert.equal(request.sampleFrames, 16_000);
assert.equal(request.language, "es");
diff --git a/packages/workspace-fs-node/README.md b/packages/workspace-fs-node/README.md
index c71aed4f..34d4903c 100644
--- a/packages/workspace-fs-node/README.md
+++ b/packages/workspace-fs-node/README.md
@@ -4,5 +4,5 @@ Reference Node filesystem implementation of the host-neutral `Workspace` contrac
Every `open()` call creates one isolated compilation session. It canonicalizes real paths, confines
SourceUnit and Source Asset reads to the configured root, rejects symlink escapes, locks each edge
-to the first bytes observed and returns defensive content-addressed attachments. It contains no
+to the first bytes observed and returns defensive Resource attachments. It contains no
Frontend, package, Core, Runtime, Provider or domain knowledge.
diff --git a/packages/workspace-fs-node/src/workspace.ts b/packages/workspace-fs-node/src/workspace.ts
index dfa8f7e7..2d9c43ce 100644
--- a/packages/workspace-fs-node/src/workspace.ts
+++ b/packages/workspace-fs-node/src/workspace.ts
@@ -1,6 +1,6 @@
-import { createHash, randomUUID } from "node:crypto";
+import { randomUUID } from "node:crypto";
import { createReadStream } from "node:fs";
-import { readFile, realpath } from "node:fs/promises";
+import { readFile, realpath, stat } from "node:fs/promises";
import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
import type {
@@ -27,8 +27,7 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {
readonly #assetRoots: readonly string[];
readonly #sourceCache = new Map<string, SourceUnit>();
readonly #assetIdentity = new Map<string, {
- readonly resource: string;
- readonly digest: BlobRef["digest"];
+ readonly resource: BlobRef["resource"];
readonly size: number;
}>();
readonly #attachments = new Map<string, ArtifactAttachment>();
@@ -124,23 +123,17 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {
}
let identity = this.#assetIdentity.get(canonical);
if (identity === undefined) {
- const hash = createHash("sha256");
- let size = 0;
- for await (const chunk of createReadStream(canonical)) {
- hash.update(chunk);
- size += chunk.byteLength;
- }
- identity = { resource: `res_${randomUUID()}`, digest: `sha256:${hash.digest("hex")}`, size };
+ const size = (await stat(canonical)).size;
+ identity = { resource: `res_${randomUUID()}`, size };
this.#assetIdentity.set(canonical, identity);
}
const artifact: BlobRef = {
kind: "blob",
resource: identity.resource,
- digest: identity.digest,
size: identity.size,
mediaType: request.mediaType,
};
- const attachmentKey = `${artifact.digest}\u0000${artifact.mediaType}`;
+ const attachmentKey = `${artifact.resource}\u0000${artifact.mediaType}`;
if (!this.#attachments.has(attachmentKey)) {
this.#attachments.set(attachmentKey, {
artifact: { ...artifact },
@@ -153,8 +146,8 @@ class NodeFilesystemWorkspaceSession implements WorkspaceSession {
attachments(): readonly ArtifactAttachment[] {
return [...this.#attachments.values()]
.sort((left, right) => {
- const byDigest = left.artifact.digest.localeCompare(right.artifact.digest);
- return byDigest === 0 ? left.artifact.mediaType.localeCompare(right.artifact.mediaType) : byDigest;
+ const byResource = left.artifact.resource.localeCompare(right.artifact.resource);
+ return byResource === 0 ? left.artifact.mediaType.localeCompare(right.artifact.mediaType) : byResource;
})
.map((item) => ({ artifact: { ...item.artifact }, open: item.open }));
}
diff --git a/packages/yt-dlp/src/download.ts b/packages/yt-dlp/src/download.ts
index 15faf1b5..05966142 100644
--- a/packages/yt-dlp/src/download.ts
+++ b/packages/yt-dlp/src/download.ts
@@ -19,9 +19,8 @@
* is the same shape WhisperX and OpenCV already use for their Python programs.
*/
import { spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
import { existsSync } from "node:fs";
-import { mkdir, readdir } from "node:fs/promises";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
@@ -68,9 +67,23 @@ function serviceProject(): string {
}
}
-/** Where one link's download lives, keyed by the link so a second run finds the first one's bytes. */
-function cacheDirectory(root: string, url: string): string {
- return join(root, createHash("sha256").update(url).digest("hex").slice(0, 16));
+/** Find or allocate one readable cache directory whose `source.url` records the original locator. */
+async function cacheDirectory(root: string, url: string): Promise<string> {
+ await mkdir(root, { recursive: true });
+ const entries = await readdir(root, { withFileTypes: true });
+ for (const entry of entries) {
+ if (!entry.isDirectory() || !/^reference-[1-9][0-9]*$/u.test(entry.name)) continue;
+ const directory = join(root, entry.name);
+ if (await readFile(join(directory, "source.url"), "utf8").catch(() => undefined) === url) return directory;
+ }
+ const numbers = entries.flatMap((entry) => {
+ const match = /^reference-([1-9][0-9]*)$/u.exec(entry.name);
+ return match === null ? [] : [Number(match[1])];
+ });
+ const directory = join(root, `reference-${Math.max(0, ...numbers) + 1}`);
+ await mkdir(directory, { recursive: false });
+ await writeFile(join(directory, "source.url"), url, "utf8");
+ return directory;
}
async function existingDownload(directory: string): Promise<string | undefined> {
@@ -89,8 +102,7 @@ async function existingDownload(directory: string): Promise<string | undefined>
* happens to sit inside a playlist from fetching the playlist.
*/
export async function downloadReferenceVideo(url: string, root: string): Promise<DownloadedReference> {
- const directory = cacheDirectory(root, url);
- await mkdir(directory, { recursive: true });
+ const directory = await cacheDirectory(root, url);
const held = await existingDownload(directory);
if (held !== undefined) return { path: held, url, cached: true };
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index b41e8032..3879bdf9 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -15,12 +15,6 @@ importers:
'@hypit/artifact':
specifier: workspace:*
version: link:packages/artifact
- '@hypit/artifact-store-fs':
- specifier: workspace:*
- version: link:packages/artifact-store-fs
- '@hypit/artifact-store-s3':
- specifier: workspace:*
- version: link:packages/artifact-store-s3
'@hypit/audio-track':
specifier: workspace:*
version: link:packages/audio-track
@@ -159,9 +153,6 @@ importers:
'@hypit/provider-kie':
specifier: workspace:*
version: link:packages/provider-kie
- '@hypit/provider-media-aws-lambda':
- specifier: workspace:*
- version: link:packages/provider-media-aws-lambda
'@hypit/provider-media-local':
specifier: workspace:*
version: link:packages/provider-media-local
@@ -186,6 +177,12 @@ importers:
'@hypit/render-hyperframes':
specifier: workspace:*
version: link:packages/render-hyperframes
+ '@hypit/resource-store-fs':
+ specifier: workspace:*
+ version: link:packages/resource-store-fs
+ '@hypit/resource-store-s3':
+ specifier: workspace:*
+ version: link:packages/resource-store-s3
'@hypit/run-markup':
specifier: workspace:*
version: link:packages/run-markup
@@ -331,27 +328,6 @@ importers:
specifier: workspace:*
version: link:../protocol
- packages/artifact-store-fs:
- dependencies:
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../protocol
- '@hypit/runtime':
- specifier: workspace:*
- version: link:../runtime
-
- packages/artifact-store-s3:
- dependencies:
- '@aws-sdk/client-s3':
- specifier: 3.1103.0
- version: 3.1103.0
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../protocol
- '@hypit/runtime':
- specifier: workspace:*
- version: link:../runtime
-
packages/audio-track:
dependencies:
'@hypit/component-kit':
@@ -1930,9 +1906,6 @@ importers:
'@hypit/artifact':
specifier: workspace:*
version: link:../artifact
- '@hypit/artifact-store-fs':
- specifier: workspace:*
- version: link:../artifact-store-fs
'@hypit/compiler-node':
specifier: workspace:*
version: link:../compiler-node
@@ -1957,6 +1930,9 @@ importers:
'@hypit/provider-media-local':
specifier: workspace:*
version: link:../provider-media-local
+ '@hypit/resource-store-fs':
+ specifier: workspace:*
+ version: link:../resource-store-fs
'@hypit/semantic-take-estimate':
specifier: workspace:*
version: link:../semantic-take-estimate
@@ -2165,9 +2141,6 @@ importers:
specifier: workspace:*
version: link:../runtime-kit
devDependencies:
- '@hypit/artifact-store-fs':
- specifier: workspace:*
- version: link:../artifact-store-fs
'@hypit/component-kit':
specifier: workspace:*
version: link:../component-kit
@@ -2204,6 +2177,9 @@ importers:
'@hypit/narrative':
specifier: workspace:*
version: link:../narrative
+ '@hypit/resource-store-fs':
+ specifier: workspace:*
+ version: link:../resource-store-fs
'@hypit/runtime-local':
specifier: workspace:*
version: link:../runtime-local
@@ -2223,37 +2199,6 @@ importers:
specifier: workspace:*
version: link:../validation
- packages/provider-media-aws-lambda:
- dependencies:
- '@hypit/artifact':
- specifier: workspace:*
- version: link:../artifact
- '@hypit/endpoint-kit':
- specifier: workspace:*
- version: link:../endpoint-kit
- '@hypit/media':
- specifier: workspace:*
- version: link:../media
- '@hypit/media-pipeline':
- specifier: workspace:*
- version: link:../media-pipeline
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../protocol
- '@hypit/runtime-kit':
- specifier: workspace:*
- version: link:../runtime-kit
- '@hypit/speech':
- specifier: workspace:*
- version: link:../speech
- '@hypit/transport-aws-lambda':
- specifier: workspace:*
- version: link:../transport-aws-lambda
- devDependencies:
- '@hypit/driver-node':
- specifier: workspace:*
- version: link:../driver-node
-
packages/provider-media-local:
dependencies:
'@hypit/artifact':
@@ -2600,6 +2545,27 @@ importers:
specifier: workspace:*
version: link:../validation
+ packages/resource-store-fs:
+ dependencies:
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/runtime':
+ specifier: workspace:*
+ version: link:../runtime
+
+ packages/resource-store-s3:
+ dependencies:
+ '@aws-sdk/client-s3':
+ specifier: 3.1103.0
+ version: 3.1103.0
+ '@hypit/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+ '@hypit/runtime':
+ specifier: workspace:*
+ version: link:../runtime
+
packages/run:
dependencies:
'@hypit/elaborator':
@@ -2684,9 +2650,6 @@ importers:
packages/runtime-local:
dependencies:
- '@hypit/artifact-store-fs':
- specifier: workspace:*
- version: link:../artifact-store-fs
'@hypit/build-result':
specifier: workspace:*
version: link:../build-result
@@ -2711,6 +2674,9 @@ importers:
'@hypit/protocol':
specifier: workspace:*
version: link:../protocol
+ '@hypit/resource-store-fs':
+ specifier: workspace:*
+ version: link:../resource-store-fs
'@hypit/runtime':
specifier: workspace:*
version: link:../runtime
@@ -3123,6 +3089,9 @@ importers:
'@hypit/audio-track-studio':
specifier: workspace:*
version: link:../audio-track-studio
+ '@hypit/build-result':
+ specifier: workspace:*
+ version: link:../build-result
'@hypit/caption-fine-studio':
specifier: workspace:*
version: link:../caption-fine-studio
@@ -3521,37 +3490,6 @@ importers:
services/image-opencv: {}
- services/media-lambda:
- dependencies:
- '@hypit/artifact-store-s3':
- specifier: workspace:*
- version: link:../../packages/artifact-store-s3
- '@hypit/media':
- specifier: workspace:*
- version: link:../../packages/media
- '@hypit/media-execution':
- specifier: workspace:*
- version: link:../../packages/media-execution
- '@hypit/media-pipeline':
- specifier: workspace:*
- version: link:../../packages/media-pipeline
- '@hypit/protocol':
- specifier: workspace:*
- version: link:../../packages/protocol
- '@hypit/provider-media-aws-lambda':
- specifier: workspace:*
- version: link:../../packages/provider-media-aws-lambda
- '@hypit/speech':
- specifier: workspace:*
- version: link:../../packages/speech
- '@hypit/transport-aws-lambda':
- specifier: workspace:*
- version: link:../../packages/transport-aws-lambda
- devDependencies:
- esbuild:
- specifier: ^0.25.0
- version: 0.25.12
-
services/whisperx: {}
services/yt-dlp: {}
diff --git a/services/image-opencv/README.md b/services/image-opencv/README.md
index 3c8571f6..dd812ded 100644
--- a/services/image-opencv/README.md
+++ b/services/image-opencv/README.md
@@ -29,5 +29,5 @@ Then configure the Provider with the environment's interpreter:
The Provider starts one bounded, shell-free Python process for each admitted Need. The ordinary
SVML Runtime Scheduler owns concurrency. The Python process reads only its explicit temporary input
-and Program files and writes one explicit output image; it has no network, artifact-store, author
+and Program files and writes one explicit output image; it has no network, Resource Store, author
source or BuildState API.
diff --git a/services/media-lambda/README.md b/services/media-lambda/README.md
deleted file mode 100644
index 9eb2d563..00000000
--- a/services/media-lambda/README.md
+++ /dev/null
@@ -1,125 +0,0 @@
-# Hypit media execution service
-
-This service answers nine media Needs in AWS Lambda: inspect, normalize, transform, extract audio,
-extract frame, still-video rendering, speech-evidence projection, timeline audio and mux. It is deployment state, not an
-author-importable SVML package.
-
-It owns no media semantics. `@hypit/media-execution` contains the FFmpeg commands and
-frame/sample arithmetic shared with `@hypit/provider-media-local`. This directory contributes
-an S3 byte gateway, a managed-runtime handler and one declarative AWS deployment.
-
-## One stack, two immutable code objects
-
-`template.yaml` makes one CloudFormation stack own:
-
-- the narrowly scoped Lambda execution role;
-- its retained CloudWatch log group;
-- an immutable FFmpeg 8.0.1 Layer version;
-- the Node.js 22 media function;
-- a retained, immutable function version;
-- an explicit reserved-concurrency ceiling.
-
-The ArtifactStore bucket and deployment-artifact bucket remain external resources. The same
-ArtifactStore can serve local and Lambda Endpoints; the deployment bucket contains code, not Build
-Artifacts.
-
-`build.mjs` produces the small function ZIP. `build-layer.mjs` downloads one exact BtbN archive,
-checks its SHA-256, retains only `ffmpeg`, `ffprobe`, their shared libraries and the upstream
-license, and creates a deterministic Layer ZIP. The Layer provenance is embedded as
-`/opt/hypit-layer.json`. Set `HYPIT_FFMPEG_SOURCE` to an already downloaded archive for an
-offline build; it is accepted only when its digest matches the pin.
-
-Shared-library links are copied verbatim from the upstream archive. The builder rejects absolute,
-escaping or dangling links before producing the ZIP, so a build-machine path cannot become a
-silent `/opt/lib` runtime failure.
-
-The selected build is:
-
-```text
-FFmpeg n8.0.1-66-g27b8d1a017
-linux64 GPL shared, x86-64
-source sha256 38f5363bef58d74547e5055846d76d8b20bb2872a87b0aab71611b010b437a6f
-```
-
-AWS mounts Layer `bin/` and `lib/` as `/opt/bin` and `/opt/lib`. The handler additionally executes
-both binaries with `-version` once per warm environment and refuses work unless both report 8.0.1.
-
-## Why the build is GPL, and the line it must not cross
-
-This is a GPL build, not the LGPL one from the same upstream release. The encode path requires
-`libx264`, which is a GPL component: it exists only in builds configured with `--enable-gpl`.
-`REQUIRED_ENCODERS` in `packages/media-execution/src/toolchain.ts` names it explicitly, so an LGPL
-archive would fail the toolchain probe rather than degrade quietly. Moving to the LGPL archive is
-therefore not a URL change; it means replacing the H.264 encoder and re-tuning every encode flag.
-
-The GPL obligations attach to whoever *conveys* the binary. Here nobody does. `build-layer.mjs`
-downloads the archive on the operator's own machine, and `deploy.sh` refuses to run unless the
-resolved AWS account matches the configured `AWS_ACCOUNT_ID`, so the Layer is published only into
-the operator's own account. The operator obtains FFmpeg from its upstream, not from Hypit.
-
-That boundary is the whole argument, so keep it intact:
-
-- Do not publish a prebuilt Layer ARN for others to consume, and do not ship or mirror the built
- `ffmpeg-layer.zip`. Either one makes the publisher a distributor of GPL binaries, which then
- requires offering the corresponding FFmpeg source alongside it.
-- Distributing that Layer would additionally collide with the repository's own LICENSE, whose extra
- conditions GPL-3.0 section 7 does not permit a distributor to add.
-- The upstream `LICENSE.txt` is already copied into the Layer and the provenance is recorded in
- `/opt/hypit-layer.json`. Keep both.
-
-## Authority and bytes
-
-The function role can only read and write objects in the selected ArtifactStore bucket and append
-to its own log group. It cannot deploy code, publish Layers, inspect IAM or access the deployment
-bucket.
-
-The deployer needs the reviewed actions in `iam/publisher.json`. CloudFormation uses the deployer's
-AWS credential chain; access keys never enter source, a Runtime Profile or BuildState.
-
-Media bytes never enter the synchronous Lambda request. Requests identify content-addressed S3
-objects and results are written back through the same `@hypit/artifact-store-s3` key rule.
-
-## Build without AWS
-
-```bash
-pnpm build:media-lambda
-pnpm build:media-lambda-layer
-```
-
-Ignored output is written under `services/media-lambda/build/`. The two artifact manifests record
-the function bundle hash, ZIP hashes, exact upstream source and package sizes.
-
-## Plan, inspect, apply
-
-Deployment deliberately has two commands. `plan` may build and upload content-addressed packages,
-but it only creates a CloudFormation Change Set. `apply` accepts that exact Change Set ARN; it does
-not rebuild or silently reinterpret the plan.
-
-```bash
-export AWS_PROFILE=hypit
-export AWS_REGION=us-east-1
-export AWS_ACCOUNT_ID=123456789012
-export HYPIT_MEDIA_ENVIRONMENT=dev
-export HYPIT_MEDIA_STACK=hypit-media-dev
-export HYPIT_MEDIA_FUNCTION=hypit-media-dev
-export HYPIT_MEDIA_ROLE=HypitMediaExecution-dev
-export HYPIT_MEDIA_LAYER=hypit-ffmpeg-8-0-1
-export HYPIT_MEDIA_ARTIFACT_BUCKET=hypit-artifacts-123456789012
-export HYPIT_MEDIA_DEPLOYMENT_BUCKET=your-regional-deployment-bucket
-
-services/media-lambda/deploy.sh plan
-services/media-lambda/deploy.sh apply <exact-change-set-arn>
-```
-
-Optional infrastructure parameters are `HYPIT_MEDIA_MEMORY` (3008),
-`HYPIT_MEDIA_EPHEMERAL` (8192), `HYPIT_MEDIA_CONCURRENCY` (8) and
-`HYPIT_MEDIA_LOG_RETENTION_DAYS` (14). They are CloudFormation parameters and therefore visible
-in the Change Set.
-
-The stack outputs an immutable function-version ARN and a complete JSON Endpoint entry for
-`@hypit/provider-media-aws-lambda`. The Provider rejects an unqualified function name. Old
-function and Layer versions are retained across updates so a recorded Runtime Profile never changes
-meaning because a newer deployment happened.
-
-No paid AWS deployment runs in the normal test suite. The handler tests execute the real shared
-media implementation with local FFmpeg and an in-memory object store.
diff --git a/services/media-lambda/build-layer.mjs b/services/media-lambda/build-layer.mjs
deleted file mode 100755
index a7b677ff..00000000
--- a/services/media-lambda/build-layer.mjs
+++ /dev/null
@@ -1,178 +0,0 @@
-#!/usr/bin/env node
-import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
-import { createReadStream, createWriteStream } from "node:fs";
-import {
- chmod,
- cp,
- lstat,
- lutimes,
- mkdir,
- readlink,
- readFile,
- readdir,
- rename,
- rm,
- stat,
- utimes,
- writeFile,
-} from "node:fs/promises";
-import { Readable } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-
-const SOURCE_NAME = "ffmpeg-n8.0.1-66-g27b8d1a017-linux64-gpl-shared-8.0.tar.xz";
-const SOURCE_URL =
- `https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-02-28-12-59/${SOURCE_NAME}`;
-const SOURCE_SHA256 = "38f5363bef58d74547e5055846d76d8b20bb2872a87b0aab71611b010b437a6f";
-const FFmpeg_VERSION = "8.0.1";
-const EPOCH = new Date("1980-01-01T00:00:00.000Z");
-
-const root = dirname(fileURLToPath(import.meta.url));
-const out = join(root, "build");
-const source = process.env.HYPIT_FFMPEG_SOURCE ?? join(out, SOURCE_NAME);
-const work = join(out, "ffmpeg-layer-work");
-const extracted = join(work, "source");
-const layer = join(work, "layer");
-const archive = join(out, "ffmpeg-layer.zip");
-const manifestPath = join(out, "ffmpeg-layer-artifact.json");
-
-async function sha256(path) {
- const hash = createHash("sha256");
- for await (const chunk of createReadStream(path)) hash.update(chunk);
- return hash.digest("hex");
-}
-
-async function ensureSource() {
- await mkdir(out, { recursive: true });
- try {
- if (await sha256(source) === SOURCE_SHA256) return;
- } catch (error) {
- if (error?.code !== "ENOENT") throw error;
- }
- if (process.env.HYPIT_FFMPEG_SOURCE !== undefined) {
- throw new Error(`HYPIT_FFMPEG_SOURCE does not match pinned sha256 ${SOURCE_SHA256}`);
- }
-
- const temporary = `${source}.partial`;
- await rm(temporary, { force: true });
- const response = await fetch(SOURCE_URL, { redirect: "follow" });
- if (!response.ok || response.body === null) {
- throw new Error(`failed to download pinned FFmpeg archive: HTTP ${response.status}`);
- }
- await pipeline(Readable.fromWeb(response.body), createWriteStream(temporary, { mode: 0o644 }));
- const actual = await sha256(temporary);
- if (actual !== SOURCE_SHA256) {
- await rm(temporary, { force: true });
- throw new Error(`FFmpeg source digest mismatch: expected ${SOURCE_SHA256}, got ${actual}`);
- }
- await rename(temporary, source);
-}
-
-async function entriesUnder(path, found = []) {
- const children = (await readdir(path)).sort();
- for (const name of children) {
- const child = join(path, name);
- const info = await lstat(child);
- if (info.isDirectory()) await entriesUnder(child, found);
- else found.push(child);
- }
- return found;
-}
-
-async function normalize(path) {
- const children = (await readdir(path)).sort();
- for (const name of children) {
- const child = join(path, name);
- const info = await lstat(child);
- if (info.isDirectory()) {
- await normalize(child);
- await chmod(child, 0o755);
- await utimes(child, EPOCH, EPOCH);
- } else if (info.isSymbolicLink()) {
- await lutimes(child, EPOCH, EPOCH);
- } else {
- await chmod(child, relative(layer, child).startsWith("bin/") ? 0o755 : 0o644);
- await utimes(child, EPOCH, EPOCH);
- }
- }
- await chmod(path, 0o755);
- await utimes(path, EPOCH, EPOCH);
-}
-
-await ensureSource();
-if (await sha256(source) !== SOURCE_SHA256) throw new Error("pinned FFmpeg source changed during build");
-await rm(work, { recursive: true, force: true });
-await rm(archive, { force: true });
-await mkdir(extracted, { recursive: true });
-await mkdir(layer, { recursive: true });
-await promisify(execFile)("tar", ["-xf", source, "-C", extracted], { windowsHide: true });
-
-const roots = (await readdir(extracted)).sort();
-if (roots.length !== 1) throw new Error(`FFmpeg archive must have one root directory; got ${roots.length}`);
-const upstream = join(extracted, roots[0]);
-for (const name of ["bin/ffmpeg", "bin/ffprobe", "lib", "LICENSE.txt"]) {
- await mkdir(dirname(join(layer, name)), { recursive: true });
- await cp(join(upstream, name), join(layer, name), {
- recursive: true,
- dereference: false,
- // Node otherwise resolves copied links against the source tree and writes
- // an absolute build-machine path. Such a Layer looks complete in `unzip
- // -l` but its libraries cannot be found under /opt at runtime.
- verbatimSymlinks: true,
- });
-}
-
-const provenance = {
- contract: "hypit.ffmpeg-lambda-layer@1",
- ffmpegVersion: FFmpeg_VERSION,
- architecture: "x86_64",
- upstream: { url: SOURCE_URL, sha256: SOURCE_SHA256 },
- paths: { ffmpeg: "/opt/bin/ffmpeg", ffprobe: "/opt/bin/ffprobe" },
- license: "GPL-3.0-or-later",
-};
-await writeFile(join(layer, "hypit-layer.json"), `${JSON.stringify(provenance, null, 2)}\n`);
-await normalize(layer);
-
-const files = await entriesUnder(layer);
-for (const file of files) {
- const info = await lstat(file);
- if (!info.isSymbolicLink()) continue;
- const target = await readlink(file);
- if (isAbsolute(target)) throw new Error(`${relative(layer, file)} has an absolute symlink target: ${target}`);
- const resolved = resolve(dirname(file), target);
- const withinLayer = relative(layer, resolved);
- if (withinLayer.startsWith("..") || isAbsolute(withinLayer)) {
- throw new Error(`${relative(layer, file)} escapes the Layer: ${target}`);
- }
- await stat(resolved);
-}
-for (const binary of [join(layer, "bin/ffmpeg"), join(layer, "bin/ffprobe")]) {
- const magic = await readFile(binary);
- if (magic.length < 20 || !magic.subarray(0, 4).equals(Buffer.from([0x7f, 0x45, 0x4c, 0x46]))) {
- throw new Error(`${relative(layer, binary)} is not an ELF binary`);
- }
- if (magic.readUInt16LE(18) !== 62) throw new Error(`${relative(layer, binary)} is not x86-64`);
-}
-
-await promisify(execFile)("zip", [
- "-X", "-q", "-y", archive,
- ...files.map((path) => relative(layer, path)),
-], { cwd: layer, windowsHide: true, env: { ...process.env, TZ: "UTC" } });
-
-let uncompressedBytes = 0;
-for (const file of files) uncompressedBytes += (await lstat(file)).size;
-const archiveBytes = (await stat(archive)).size;
-const archiveSha256 = await sha256(archive);
-const artifact = {
- ...provenance,
- archiveSha256,
- archiveBytes,
- uncompressedBytes,
- entryCount: files.length,
-};
-await writeFile(manifestPath, `${JSON.stringify(artifact, null, 2)}\n`);
-await rm(work, { recursive: true, force: true });
-process.stdout.write(`${JSON.stringify(artifact, null, 2)}\n`);
diff --git a/services/media-lambda/build.mjs b/services/media-lambda/build.mjs
deleted file mode 100755
index b48fb3ad..00000000
--- a/services/media-lambda/build.mjs
+++ /dev/null
@@ -1,84 +0,0 @@
-#!/usr/bin/env node
-// Bundles the handler into a small managed-runtime ZIP. FFmpeg is deliberately
-// absent: it is an independently versioned Lambda Layer mounted at /opt.
-import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
-import { chmod, mkdir, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-import { build } from "esbuild";
-
-const root = dirname(fileURLToPath(import.meta.url));
-const out = join(root, "build");
-await mkdir(out, { recursive: true });
-
-const deployment = {
- contract: "hypit.media-lambda-deployment@1",
- runtime: "nodejs22.x",
- architecture: "x86_64",
- handler: "index.handler",
- ffmpegVersion: "8.0.1",
- ffmpegPath: "/opt/bin/ffmpeg",
- ffprobePath: "/opt/bin/ffprobe",
- ffmpegLibraryPath: "/opt/lib",
-};
-const entry = join(out, "index.mjs");
-const archive = join(out, "function.zip");
-for (const path of [
- entry,
- archive,
- join(out, "deployment.json"),
- join(out, "bundle-hash.txt"),
- join(out, "function-artifact.json"),
-]) await rm(path, { force: true });
-
-const result = await build({
- entryPoints: [join(root, "src/handler.ts")],
- outfile: entry,
- bundle: true,
- platform: "node",
- target: "node22",
- format: "esm",
- // The AWS SDK is bundled rather than taken from the runtime, so the ZIP
- // pins the same client version the tests ran against.
- banner: { js: "import{createRequire}from'node:module';const require=createRequire(import.meta.url);" },
- metafile: true,
- logLevel: "info",
-});
-if (result.errors.length > 0) process.exit(1);
-
-const bundle = await readFile(entry);
-const deploymentBytes = Buffer.from(`${JSON.stringify(deployment)}\n`, "utf8");
-const hash = createHash("sha256").update(bundle).update(deploymentBytes).digest("hex");
-await writeFile(join(out, "deployment.json"), deploymentBytes);
-await writeFile(join(out, "bundle-hash.txt"), `${hash}\n`);
-
-// Strip host-specific metadata and hold the only archive member at a stable
-// timestamp. The Build identity is the source/deployment hash above; this also
-// keeps repeated ZIPs byte-stable on the reference macOS/Linux toolchain.
-await chmod(entry, 0o644);
-const epoch = new Date("1980-01-01T00:00:00.000Z");
-await utimes(entry, epoch, epoch);
-await promisify(execFile)("zip", ["-X", "-q", "-j", archive, entry], {
- windowsHide: true,
- env: { ...process.env, TZ: "UTC" },
-});
-const archiveStat = await stat(archive);
-const archiveBytes = await readFile(archive);
-const archiveSha256 = createHash("sha256").update(archiveBytes).digest();
-const functionArtifact = {
- contract: "hypit.media-lambda-function-artifact@1",
- bundleHash: hash,
- archiveSha256: archiveSha256.toString("hex"),
- codeSha256: archiveSha256.toString("base64"),
- archiveBytes: archiveStat.size,
-};
-await writeFile(join(out, "function-artifact.json"),
- `${JSON.stringify(functionArtifact, null, 2)}\n`);
-
-process.stdout.write(`${JSON.stringify({
- ...functionArtifact,
- bundleBytes: bundle.byteLength,
- deployment,
-}, null, 2)}\n`);
diff --git a/services/media-lambda/deploy.sh b/services/media-lambda/deploy.sh
deleted file mode 100755
index f15d2d8e..00000000
--- a/services/media-lambda/deploy.sh
+++ /dev/null
@@ -1,131 +0,0 @@
-#!/usr/bin/env bash
-# Plan or apply the complete, long-lived Media Lambda CloudFormation stack.
-set -euo pipefail
-
-operation="${1:-}"
-if [ "$operation" != plan ] && [ "$operation" != apply ]; then
- printf 'usage: %s plan | %s apply <change-set-arn>\n' "$0" "$0" >&2
- exit 2
-fi
-
-: "${AWS_REGION:?set AWS_REGION, e.g. us-east-1}"
-: "${AWS_ACCOUNT_ID:?set AWS_ACCOUNT_ID, your 12-digit account id}"
-: "${HYPIT_MEDIA_ENVIRONMENT:?set HYPIT_MEDIA_ENVIRONMENT, e.g. dev}"
-: "${HYPIT_MEDIA_STACK:?set HYPIT_MEDIA_STACK, e.g. hypit-media-dev}"
-
-here="$(cd "$(dirname "$0")" && pwd)"
-caller_account="$(aws sts get-caller-identity --query Account --output text)"
-if [ "$caller_account" != "$AWS_ACCOUNT_ID" ]; then
- printf 'AWS credential chain resolves account %s, not configured account %s\n' \
- "$caller_account" "$AWS_ACCOUNT_ID" >&2
- exit 2
-fi
-
-if [ "$operation" = apply ]; then
- change_set="${2:?apply requires the exact change-set ARN printed by plan}"
- stack="$(aws cloudformation describe-change-set --region "$AWS_REGION" \
- --change-set-name "$change_set" --query StackName --output text)"
- if [ "$stack" != "$HYPIT_MEDIA_STACK" ]; then
- printf 'change set belongs to %s, not configured stack %s\n' "$stack" "$HYPIT_MEDIA_STACK" >&2
- exit 2
- fi
- stack_status="$(aws cloudformation describe-stacks --region "$AWS_REGION" \
- --stack-name "$stack" --query 'Stacks[0].StackStatus' --output text)"
- aws cloudformation execute-change-set --region "$AWS_REGION" --change-set-name "$change_set"
- if [ "$stack_status" = REVIEW_IN_PROGRESS ]; then
- aws cloudformation wait stack-create-complete --region "$AWS_REGION" --stack-name "$stack"
- else
- aws cloudformation wait stack-update-complete --region "$AWS_REGION" --stack-name "$stack"
- fi
- aws cloudformation describe-stacks --region "$AWS_REGION" --stack-name "$stack" \
- --query 'Stacks[0].Outputs[].{Key:OutputKey,Value:OutputValue}' --output table
- exit 0
-fi
-
-: "${HYPIT_MEDIA_ARTIFACT_BUCKET:?set HYPIT_MEDIA_ARTIFACT_BUCKET}"
-: "${HYPIT_MEDIA_DEPLOYMENT_BUCKET:?set HYPIT_MEDIA_DEPLOYMENT_BUCKET}"
-: "${HYPIT_MEDIA_FUNCTION:?set HYPIT_MEDIA_FUNCTION}"
-: "${HYPIT_MEDIA_ROLE:?set HYPIT_MEDIA_ROLE}"
-: "${HYPIT_MEDIA_LAYER:?set HYPIT_MEDIA_LAYER}"
-
-memory="${HYPIT_MEDIA_MEMORY:-3008}"
-ephemeral="${HYPIT_MEDIA_EPHEMERAL:-8192}"
-concurrency="${HYPIT_MEDIA_CONCURRENCY:-8}"
-retention="${HYPIT_MEDIA_LOG_RETENTION_DAYS:-14}"
-
-printf 'Building immutable function and FFmpeg Layer artifacts\n'
-(cd "$here" && node build.mjs)
-(cd "$here" && node build-layer.mjs)
-
-function_hash="$(node -p "require('$here/build/function-artifact.json').archiveSha256")"
-function_code_sha="$(node -p "require('$here/build/function-artifact.json').codeSha256")"
-bundle_hash="$(node -p "require('$here/build/function-artifact.json').bundleHash")"
-layer_hash="$(node -p "require('$here/build/ffmpeg-layer-artifact.json').archiveSha256")"
-function_key="hypit/media-lambda/functions/${function_hash}.zip"
-layer_key="hypit/media-lambda/layers/${layer_hash}.zip"
-
-uncompressed_layer="$(node -p "require('$here/build/ffmpeg-layer-artifact.json').uncompressedBytes")"
-uncompressed_function="$(unzip -l "$here/build/function.zip" | awk 'END {print $1}')"
-if [ "$((uncompressed_layer + uncompressed_function))" -ge 262144000 ]; then
- printf 'function plus Layer exceed Lambda uncompressed ZIP quota\n' >&2
- exit 1
-fi
-
-printf 'Uploading content-addressed deployment artifacts\n'
-aws s3 cp "$here/build/function.zip" \
- "s3://${HYPIT_MEDIA_DEPLOYMENT_BUCKET}/${function_key}" \
- --region "$AWS_REGION" --only-show-errors --checksum-algorithm SHA256
-aws s3 cp "$here/build/ffmpeg-layer.zip" \
- "s3://${HYPIT_MEDIA_DEPLOYMENT_BUCKET}/${layer_key}" \
- --region "$AWS_REGION" --only-show-errors --checksum-algorithm SHA256
-
-stack_status="$(aws cloudformation describe-stacks --region "$AWS_REGION" \
- --stack-name "$HYPIT_MEDIA_STACK" --query 'Stacks[0].StackStatus' --output text 2>/dev/null || true)"
-if [ -z "$stack_status" ] || [ "$stack_status" = REVIEW_IN_PROGRESS ]; then
- change_set_type=CREATE
-else
- change_set_type=UPDATE
-fi
-change_set_name="media-$(date -u +%Y%m%dT%H%M%SZ)-${function_hash:0:8}-${layer_hash:0:8}"
-
-printf 'Creating unexecuted %s Change Set %s\n' "$change_set_type" "$change_set_name"
-change_set_arn="$(aws cloudformation create-change-set --region "$AWS_REGION" \
- --stack-name "$HYPIT_MEDIA_STACK" \
- --change-set-name "$change_set_name" \
- --change-set-type "$change_set_type" \
- --description "Hypit media function ${function_hash}; layer ${layer_hash}" \
- --template-body "file://${here}/template.yaml" \
- --capabilities CAPABILITY_NAMED_IAM \
- --parameters \
- "ParameterKey=EnvironmentName,ParameterValue=${HYPIT_MEDIA_ENVIRONMENT}" \
- "ParameterKey=FunctionName,ParameterValue=${HYPIT_MEDIA_FUNCTION}" \
- "ParameterKey=ExecutionRoleName,ParameterValue=${HYPIT_MEDIA_ROLE}" \
- "ParameterKey=LayerName,ParameterValue=${HYPIT_MEDIA_LAYER}" \
- "ParameterKey=ArtifactBucket,ParameterValue=${HYPIT_MEDIA_ARTIFACT_BUCKET}" \
- "ParameterKey=DeploymentBucket,ParameterValue=${HYPIT_MEDIA_DEPLOYMENT_BUCKET}" \
- "ParameterKey=FunctionCodeKey,ParameterValue=${function_key}" \
- "ParameterKey=FunctionCodeSha256,ParameterValue=${function_code_sha}" \
- "ParameterKey=FunctionBundleHash,ParameterValue=${bundle_hash}" \
- "ParameterKey=LayerCodeKey,ParameterValue=${layer_key}" \
- "ParameterKey=LayerArchiveHash,ParameterValue=${layer_hash}" \
- "ParameterKey=MemorySize,ParameterValue=${memory}" \
- "ParameterKey=EphemeralStorageSize,ParameterValue=${ephemeral}" \
- "ParameterKey=ReservedConcurrency,ParameterValue=${concurrency}" \
- "ParameterKey=LogRetentionDays,ParameterValue=${retention}" \
- --query Id --output text)"
-printf 'Created %s\n' "$change_set_arn"
-
-if ! aws cloudformation wait change-set-create-complete --region "$AWS_REGION" \
- --change-set-name "$change_set_arn"; then
- aws cloudformation describe-change-set --region "$AWS_REGION" \
- --change-set-name "$change_set_arn" \
- --query '{Status:Status,Reason:StatusReason}' --output json >&2
- exit 1
-fi
-
-aws cloudformation describe-change-set --region "$AWS_REGION" \
- --change-set-name "$change_set_arn" \
- --query '{Stack:StackName,Status:Status,ExecutionStatus:ExecutionStatus,Changes:Changes[].ResourceChange.{Action:Action,LogicalId:LogicalResourceId,Type:ResourceType,Replacement:Replacement}}' \
- --output json
-printf '\nReview the change set above, then apply exactly:\n\n'
-printf ' %q apply %q\n' "$0" "$change_set_arn"
diff --git a/services/media-lambda/iam/publisher.json b/services/media-lambda/iam/publisher.json
deleted file mode 100644
index e211ab6e..00000000
--- a/services/media-lambda/iam/publisher.json
+++ /dev/null
@@ -1,88 +0,0 @@
-{
- "Version": "2012-10-17",
- "Statement": [
- {
- "Sid": "ManageThePinnedFfmpegLayer",
- "Effect": "Allow",
- "Action": ["lambda:PublishLayerVersion", "lambda:GetLayerVersion"],
- "Resource": [
- "arn:aws:lambda:REGION:ACCOUNT_ID:layer:hypit-ffmpeg-8-0-1",
- "arn:aws:lambda:REGION:ACCOUNT_ID:layer:hypit-ffmpeg-8-0-1:*"
- ]
- },
- {
- "Sid": "PublishTheFunction",
- "Effect": "Allow",
- "Action": [
- "lambda:CreateFunction",
- "lambda:GetFunction",
- "lambda:GetFunctionConfiguration",
- "lambda:GetFunctionConcurrency",
- "lambda:GetRuntimeManagementConfig",
- "lambda:InvokeFunction",
- "lambda:ListTags",
- "lambda:ListVersionsByFunction",
- "lambda:PublishVersion",
- "lambda:PutRuntimeManagementConfig",
- "lambda:UpdateFunctionCode",
- "lambda:UpdateFunctionConfiguration",
- "lambda:DeleteFunction",
- "lambda:PutFunctionConcurrency",
- "lambda:TagResource",
- "lambda:UntagResource"
- ],
- "Resource": "arn:aws:lambda:REGION:ACCOUNT_ID:function:hypit-media*"
- },
- {
- "Sid": "HandTheExecutionRoleToTheFunction",
- "Effect": "Allow",
- "Action": [
- "iam:CreateRole",
- "iam:GetRole",
- "iam:PutRolePolicy",
- "iam:DeleteRolePolicy",
- "iam:DeleteRole",
- "iam:PassRole",
- "iam:TagRole",
- "iam:UntagRole"
- ],
- "Resource": "arn:aws:iam::ACCOUNT_ID:role/HypitMediaExecution-*"
- },
- {
- "Sid": "ManageTheMediaStack",
- "Effect": "Allow",
- "Action": [
- "cloudformation:CreateStack",
- "cloudformation:UpdateStack",
- "cloudformation:CreateChangeSet",
- "cloudformation:DescribeStacks",
- "cloudformation:DescribeStackEvents",
- "cloudformation:DescribeChangeSet",
- "cloudformation:ExecuteChangeSet",
- "cloudformation:DeleteChangeSet"
- ],
- "Resource": "arn:aws:cloudformation:REGION:ACCOUNT_ID:stack/hypit-media-*/*"
- },
- {
- "Sid": "ManageTheMediaLogGroup",
- "Effect": "Allow",
- "Action": [
- "logs:CreateLogGroup",
- "logs:DeleteLogGroup",
- "logs:PutRetentionPolicy"
- ],
- "Resource": "arn:aws:logs:REGION:ACCOUNT_ID:log-group:/aws/lambda/hypit-media-*"
- },
- {
- "Sid": "TheArtifactStore",
- "Effect": "Allow",
- "Action": ["s3:GetObject", "s3:PutObject", "s3:ListBucket", "s3:DeleteObject"],
- "Resource": [
- "arn:aws:s3:::BUCKET",
- "arn:aws:s3:::BUCKET/*",
- "arn:aws:s3:::DEPLOYMENT_BUCKET",
- "arn:aws:s3:::DEPLOYMENT_BUCKET/hypit/media-lambda/*"
- ]
- }
- ]
-}
diff --git a/services/media-lambda/package.json b/services/media-lambda/package.json
deleted file mode 100644
index 35bbf8e3..00000000
--- a/services/media-lambda/package.json
+++ /dev/null
@@ -1,27 +0,0 @@
-{
- "name": "@hypit/media-lambda",
- "version": "0.0.0-dev",
- "license": "SEE LICENSE IN LICENSE",
- "private": true,
- "type": "module",
- "exports": {
- ".": "./src/handler.ts"
- },
- "dependencies": {
- "@hypit/artifact-store-s3": "workspace:*",
- "@hypit/media": "workspace:*",
- "@hypit/media-execution": "workspace:*",
- "@hypit/media-pipeline": "workspace:*",
- "@hypit/protocol": "workspace:*",
- "@hypit/provider-media-aws-lambda": "workspace:*",
- "@hypit/speech": "workspace:*",
- "@hypit/transport-aws-lambda": "workspace:*"
- },
- "scripts": {
- "build": "node build.mjs",
- "build:layer": "node build-layer.mjs"
- },
- "devDependencies": {
- "esbuild": "^0.25.0"
- }
-}
diff --git a/services/media-lambda/src/handler.ts b/services/media-lambda/src/handler.ts
deleted file mode 100644
index f05387c2..00000000
--- a/services/media-lambda/src/handler.ts
+++ /dev/null
@@ -1,206 +0,0 @@
-import { AwsS3ObjectClient, S3ArtifactStore } from "@hypit/artifact-store-s3";
-import type { S3ObjectClient } from "@hypit/artifact-store-s3";
-import {
- executeInspectMedia,
- executeExtractAudio,
- executeExtractFrame,
- executeMuxProgramMedia,
- executeNormalizeMedia,
- executeProjectSpeechEvidenceAudio,
- executeRenderTimelineAudio,
- executeRenderStillVideo,
- executeTransformMedia,
-} from "@hypit/media-execution";
-import type { MediaExecutionEnvironment, MediaOperationResult } from "@hypit/media-execution";
-import { execFile } from "node:child_process";
-import { createReadStream } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { promisify } from "node:util";
-import type { BlobRef, CanonicalValue, Digest } from "@hypit/protocol";
-import {
- MEDIA_LAMBDA_RESPONSE,
- parseMediaLambdaRequest,
-} from "@hypit/provider-media-aws-lambda";
-import type { MediaLambdaArtifactLocation, MediaLambdaOperation } from "@hypit/provider-media-aws-lambda";
-
-/**
- * The whole function.
- *
- * It owns no media logic: `@hypit/media-execution` holds the ffmpeg argv
- * and the frame arithmetic, and the same code answers a local Build. What is
- * particular to this deployment is only where the bytes live and which ffmpeg
- * binary its immutable Layer carries.
- */
-const OPERATIONS: Record<
- MediaLambdaOperation,
- (env: MediaExecutionEnvironment, constraints: CanonicalValue) => Promise<MediaOperationResult>
-> = {
- "inspect": executeInspectMedia,
- "normalize": executeNormalizeMedia,
- "transform": executeTransformMedia,
- "extract-audio": executeExtractAudio,
- "extract-frame": executeExtractFrame,
- "render-still": executeRenderStillVideo,
- "project-speech-evidence-audio": executeProjectSpeechEvidenceAudio,
- "render-audio": executeRenderTimelineAudio,
- "mux": executeMuxProgramMedia,
-};
-
-const FFMPEG_PATH = process.env.FFMPEG_PATH ?? "/opt/bin/ffmpeg";
-const FFPROBE_PATH = process.env.FFPROBE_PATH ?? "/opt/bin/ffprobe";
-const FFMPEG_LIBRARY_PATH = process.env.HYPIT_FFMPEG_LIBRARY_PATH;
-const run = promisify(execFile);
-
-function positiveInteger(value: string | undefined, fallback: number): number {
- if (value === undefined) return fallback;
- const parsed = Number.parseInt(value, 10);
- if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new Error(`${value} is not a positive integer`);
- return parsed;
-}
-
-/**
- * The bucket, addressed by the same content-addressing rule the ArtifactStore
- * uses. Writes are conditional, so two functions racing on identical bytes
- * agree rather than conflict.
- */
-function gateway(location: MediaLambdaArtifactLocation, client: S3ObjectClient) {
- const store = new S3ArtifactStore({
- bucket: location.bucket,
- ...(location.prefix === undefined ? {} : { prefix: location.prefix }),
- client,
- });
- return {
- async get(source: BlobRef): Promise<Uint8Array | undefined> {
- return await store.get(source.digest);
- },
- async open(source: BlobRef): Promise<AsyncIterable<Uint8Array> | undefined> {
- if (store.open !== undefined) return await store.open(source.digest);
- const bytes = await store.get(source.digest);
- return bytes === undefined ? undefined : (async function* () { yield bytes; })();
- },
- async put(bytes: Uint8Array, mediaType: string): Promise<BlobRef> {
- return await store.put(bytes, mediaType);
- },
- async putFile(path: string, mediaType: string): Promise<BlobRef> {
- return store.putStream === undefined
- ? await store.put(await readFile(path), mediaType)
- : await store.putStream(createReadStream(path), mediaType);
- },
- };
-}
-
-function failure(operation: MediaLambdaOperation, error: unknown) {
- const message = error instanceof Error ? error.message : String(error);
- return {
- contract: MEDIA_LAMBDA_RESPONSE,
- operation,
- ok: false as const,
- code: "MEDIA_OPERATION_FAILED",
- message,
- };
-}
-
-export type MediaLambdaHandlerOptions = {
- /** Injection point for tests, MinIO and specially configured trusted AWS clients. */
- readonly client?: S3ObjectClient;
- readonly ffmpegPath?: string;
- readonly ffprobePath?: string;
- readonly sharedLibraryPath?: string;
- /**
- * The deployed ZIP sets this to the version promised by its immutable Layer.
- * Tests and embedded handlers may omit it when their binary identity is
- * already controlled by the caller.
- */
- readonly expectedFfmpegVersion?: string;
-};
-
-function versionMatches(line: string, tool: "ffmpeg" | "ffprobe", expected: string): boolean {
- const escaped = expected.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
- return new RegExp(`^${tool} version (?:n)?${escaped}(?:[-\\s]|$)`, "u").test(line);
-}
-
-async function assertBinaryVersion(
- path: string,
- tool: "ffmpeg" | "ffprobe",
- expected: string,
- sharedLibraryPath?: string,
-): Promise<void> {
- const { stdout } = await run(path, ["-version"], {
- encoding: "utf8",
- maxBuffer: 64 * 1024,
- timeout: 10_000,
- windowsHide: true,
- env: {
- ...process.env,
- ...(sharedLibraryPath === undefined ? {} : { LD_LIBRARY_PATH: sharedLibraryPath }),
- },
- });
- const firstLine = stdout.split(/\r?\n/u, 1)[0] ?? "";
- if (!versionMatches(firstLine, tool, expected)) {
- throw new Error(`${tool} Layer mismatch: expected ${expected}, got ${firstLine || "no version"}`);
- }
-}
-
-async function assertBinaryPair(
- ffmpegPath: string,
- ffprobePath: string,
- expected: string | undefined,
- sharedLibraryPath?: string,
-): Promise<void> {
- if (expected === undefined) return;
- await Promise.all([
- assertBinaryVersion(ffmpegPath, "ffmpeg", expected, sharedLibraryPath),
- assertBinaryVersion(ffprobePath, "ffprobe", expected, sharedLibraryPath),
- ]);
-}
-
-/**
- * The handler, with its S3 client and binaries open to substitution. The
- * deployed entry point below closes them over the Layer's fixed paths; a test
- * can supply an in-memory bucket and run the real ffmpeg.
- */
-export function createMediaLambdaHandler(options: MediaLambdaHandlerOptions = {}) {
- const ffmpegPath = options.ffmpegPath ?? FFMPEG_PATH;
- const ffprobePath = options.ffprobePath ?? FFPROBE_PATH;
- const sharedLibraryPath = options.sharedLibraryPath ?? FFMPEG_LIBRARY_PATH;
- // One promise per warm execution environment. A missing or wrong Layer is a
- // typed fulfillment failure, not a deployment fact silently discovered after
- // several expensive transformations have already run.
- let binariesReady: Promise<void> | undefined;
- return async function handle(event: unknown): Promise<unknown> {
- let operation: MediaLambdaOperation = "inspect";
- try {
- const request = parseMediaLambdaRequest(event);
- operation = request.operation;
- binariesReady ??= assertBinaryPair(
- ffmpegPath,
- ffprobePath,
- options.expectedFfmpegVersion ?? process.env.HYPIT_FFMPEG_VERSION,
- sharedLibraryPath,
- );
- await binariesReady;
- const env: MediaExecutionEnvironment = {
- artifacts: gateway(request.artifacts, options.client ?? new AwsS3ObjectClient({})),
- ffmpegPath,
- ffprobePath,
- ...(sharedLibraryPath === undefined ? {} : { sharedLibraryPath }),
- processTimeoutMs: positiveInteger(process.env.HYPIT_MEDIA_TIMEOUT_MS, 14 * 60_000),
- maxProbeOutputBytes: positiveInteger(process.env.HYPIT_MEDIA_MAX_PROBE_BYTES, 256 * 1024 * 1024),
- };
- const result = await OPERATIONS[operation](env, request.constraints);
- return {
- contract: MEDIA_LAMBDA_RESPONSE,
- operation,
- ok: true as const,
- value: result.value,
- };
- } catch (error) {
- // Never thrown: the transport will not copy a failed function's payload
- // into its error, so a throw would reach the Build as "Unhandled".
- return failure(operation, error);
- }
- };
-}
-
-/** The managed-runtime ZIP's entry point. */
-export const handler = createMediaLambdaHandler();
diff --git a/services/media-lambda/template.yaml b/services/media-lambda/template.yaml
deleted file mode 100644
index 61afb7bd..00000000
--- a/services/media-lambda/template.yaml
+++ /dev/null
@@ -1,160 +0,0 @@
-AWSTemplateFormatVersion: "2010-09-09"
-Description: "Hypit media execution service: FFmpeg Layer, function, immutable version, role and logs."
-
-Parameters:
- EnvironmentName:
- Type: String
- AllowedPattern: "[a-z0-9][a-z0-9-]{0,30}"
- FunctionName:
- Type: String
- AllowedPattern: "[A-Za-z0-9-_]{1,64}"
- ExecutionRoleName:
- Type: String
- AllowedPattern: "[A-Za-z0-9+=,.@_-]{1,64}"
- LayerName:
- Type: String
- AllowedPattern: "[A-Za-z0-9-_]{1,140}"
- ArtifactBucket:
- Type: String
- DeploymentBucket:
- Type: String
- FunctionCodeKey:
- Type: String
- FunctionCodeSha256:
- Type: String
- FunctionBundleHash:
- Type: String
- LayerCodeKey:
- Type: String
- LayerArchiveHash:
- Type: String
- MemorySize:
- Type: Number
- Default: 3008
- MinValue: 1024
- MaxValue: 10240
- EphemeralStorageSize:
- Type: Number
- Default: 8192
- MinValue: 512
- MaxValue: 10240
- ReservedConcurrency:
- Type: Number
- Default: 8
- MinValue: 1
- LogRetentionDays:
- Type: Number
- Default: 14
- AllowedValues: [1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365]
-
-Resources:
- MediaLogGroup:
- Type: AWS::Logs::LogGroup
- DeletionPolicy: RetainExceptOnCreate
- UpdateReplacePolicy: Retain
- Properties:
- LogGroupName: !Sub "/aws/lambda/${FunctionName}"
- RetentionInDays: !Ref LogRetentionDays
-
- MediaExecutionRole:
- Type: AWS::IAM::Role
- Properties:
- RoleName: !Ref ExecutionRoleName
- Description: !Sub "Hypit media execution role for ${EnvironmentName}"
- AssumeRolePolicyDocument:
- Version: "2012-10-17"
- Statement:
- - Effect: Allow
- Principal:
- Service: lambda.amazonaws.com
- Action: sts:AssumeRole
- Policies:
- - PolicyName: HypitMediaArtifactsAndLogs
- PolicyDocument:
- Version: "2012-10-17"
- Statement:
- - Sid: ReadSourcesAndWriteResults
- Effect: Allow
- Action:
- - s3:GetObject
- - s3:PutObject
- Resource: !Sub "arn:${AWS::Partition}:s3:::${ArtifactBucket}/*"
- - Sid: WriteFunctionLogs
- Effect: Allow
- Action:
- - logs:CreateLogStream
- - logs:PutLogEvents
- Resource: !Sub "arn:${AWS::Partition}:logs:${AWS::Region}:${AWS::AccountId}:log-group:/aws/lambda/${FunctionName}:*"
-
- MediaFfmpegLayer:
- Type: AWS::Lambda::LayerVersion
- DeletionPolicy: RetainExceptOnCreate
- UpdateReplacePolicy: Retain
- Properties:
- LayerName: !Ref LayerName
- Description: !Sub "FFmpeg 8.0.1 x86-64 GPL shared; archive sha256 ${LayerArchiveHash}"
- Content:
- S3Bucket: !Ref DeploymentBucket
- S3Key: !Ref LayerCodeKey
- CompatibleArchitectures:
- - x86_64
- CompatibleRuntimes:
- - nodejs22.x
- LicenseInfo: GPL-3.0-or-later
-
- MediaFunction:
- Type: AWS::Lambda::Function
- DependsOn: MediaLogGroup
- Properties:
- FunctionName: !Ref FunctionName
- Description: Hypit remote media execution
- Runtime: nodejs22.x
- RuntimeManagementConfig:
- UpdateRuntimeOn: FunctionUpdate
- Handler: index.handler
- Architectures:
- - x86_64
- Role: !GetAtt MediaExecutionRole.Arn
- Code:
- S3Bucket: !Ref DeploymentBucket
- S3Key: !Ref FunctionCodeKey
- Layers:
- - !Ref MediaFfmpegLayer
- MemorySize: !Ref MemorySize
- Timeout: 900
- EphemeralStorage:
- Size: !Ref EphemeralStorageSize
- ReservedConcurrentExecutions: !Ref ReservedConcurrency
- Environment:
- Variables:
- HYPIT_MEDIA_BUNDLE_HASH: !Ref FunctionBundleHash
- HYPIT_FFMPEG_VERSION: "8.0.1"
- FFMPEG_PATH: /opt/bin/ffmpeg
- FFPROBE_PATH: /opt/bin/ffprobe
- HYPIT_FFMPEG_LIBRARY_PATH: /opt/lib
-
- MediaFunctionVersion:
- Type: AWS::Lambda::Version
- DeletionPolicy: RetainExceptOnCreate
- UpdateReplacePolicy: Retain
- Properties:
- FunctionName: !Ref MediaFunction
- CodeSha256: !Ref FunctionCodeSha256
- Description: !Sub "function ${FunctionBundleHash}; layer ${LayerArchiveHash}"
-
-Outputs:
- FunctionVersionArn:
- Description: Immutable function ARN for @hypit/provider-media-aws-lambda.
- Value: !Ref MediaFunctionVersion
- LayerVersionArn:
- Description: Immutable FFmpeg Layer version used by the function.
- Value: !Ref MediaFfmpegLayer
- ExecutionRoleArn:
- Value: !GetAtt MediaExecutionRole.Arn
- ArtifactBucketName:
- Value: !Ref ArtifactBucket
- RuntimeProfileEndpoint:
- Description: Endpoint entry; parse this output as JSON.
- Value: !Sub
- - '{"use":"@hypit/provider-media-aws-lambda","instance":"media.aws-lambda.${EnvironmentName}","lane":"media","config":{"functionArn":"${FunctionVersionArn}","bucket":"${ArtifactBucket}","region":"${AWS::Region}","defaultConcurrency":${ReservedConcurrency}}}'
- - FunctionVersionArn: !Ref MediaFunctionVersion
diff --git a/services/media-lambda/test/deployment.test.ts b/services/media-lambda/test/deployment.test.ts
deleted file mode 100644
index 21f1f316..00000000
--- a/services/media-lambda/test/deployment.test.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import assert from "node:assert/strict";
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import test from "node:test";
-import { fileURLToPath } from "node:url";
-
-const service = join(dirname(fileURLToPath(import.meta.url)), "..");
-
-test("the stack owns the complete service without granting media semantics extra authority", async () => {
- const template = await readFile(join(service, "template.yaml"), "utf8");
- for (const resource of [
- "AWS::Logs::LogGroup",
- "AWS::IAM::Role",
- "AWS::Lambda::LayerVersion",
- "AWS::Lambda::Function",
- "AWS::Lambda::Version",
- ]) assert.equal(template.includes(resource), true, `${resource} is absent from the stack`);
-
- assert.match(template, /s3:GetObject[\s\S]*s3:PutObject/u);
- assert.doesNotMatch(template, /Action:\s*["']?s3:\*/u);
- assert.doesNotMatch(template, /Resource:\s*["']?\*["']?/u);
- assert.match(template, /ReservedConcurrentExecutions: !Ref ReservedConcurrency/u);
- assert.match(template, /UpdateRuntimeOn: FunctionUpdate/u);
- assert.match(template, /HYPIT_FFMPEG_LIBRARY_PATH: \/opt\/lib/u);
- assert.equal((template.match(/DeletionPolicy: RetainExceptOnCreate/gu) ?? []).length, 3);
- assert.equal((template.match(/UpdateReplacePolicy: Retain/gu) ?? []).length, 3);
- assert.match(template, /FunctionVersionArn:[\s\S]*MediaFunctionVersion/u);
- assert.doesNotMatch(template, /!Join \[":", \[!GetAtt MediaFunction\.Arn/u);
-});
-
-test("deployment separates reviewable planning from exact change-set execution", async () => {
- const script = await readFile(join(service, "deploy.sh"), "utf8");
- assert.match(script, /operation[^\n]+plan/u);
- assert.match(script, /operation[^\n]+apply/u);
- assert.match(script, /cloudformation create-change-set/u);
- assert.match(script, /cloudformation describe-change-set/u);
- assert.match(script, /cloudformation execute-change-set/u);
- assert.doesNotMatch(script, /cloudformation deploy/u);
- assert.match(script, /functions\/\$\{function_hash\}\.zip/u);
- assert.match(script, /layers\/\$\{layer_hash\}\.zip/u);
-});
-
-test("the Layer builder pins source, architecture, license and the only installed surface", async () => {
- const builder = await readFile(join(service, "build-layer.mjs"), "utf8");
- assert.match(builder, /38f5363bef58d74547e5055846d76d8b20bb2872a87b0aab71611b010b437a6f/u);
- assert.match(builder, /linux64-gpl-shared-8\.0\.tar\.xz/u);
- assert.match(builder, /\["bin\/ffmpeg", "bin\/ffprobe", "lib", "LICENSE\.txt"\]/u);
- assert.match(builder, /magic\.readUInt16LE\(18\) !== 62/u);
- assert.match(builder, /GPL-3\.0-or-later/u);
- assert.match(builder, /verbatimSymlinks: true/u);
- assert.match(builder, /isAbsolute\(target\)/u);
- assert.match(builder, /await stat\(resolved\)/u);
-});
diff --git a/services/media-lambda/test/handler.test.ts b/services/media-lambda/test/handler.test.ts
deleted file mode 100644
index a8b58d18..00000000
--- a/services/media-lambda/test/handler.test.ts
+++ /dev/null
@@ -1,129 +0,0 @@
-import assert from "node:assert/strict";
-import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import test from "node:test";
-import { promisify } from "node:util";
-
-import { s3ArtifactKey } from "@hypit/artifact-store-s3";
-import type { S3ObjectClient } from "@hypit/artifact-store-s3";
-import type { Digest } from "@hypit/protocol";
-
-import { createMediaLambdaHandler } from "../src/handler.js";
-
-const run = promisify(execFile);
-
-/** The bucket, in memory. Conditional writes behave as S3's do. */
-class Bucket implements S3ObjectClient {
- readonly values = new Map<string, Uint8Array>();
- async put(input: Parameters<S3ObjectClient["put"]>[0]): Promise<void> {
- if (input.IfNoneMatch === "*" && this.values.has(input.Key!)) {
- throw { $metadata: { httpStatusCode: 412 } };
- }
- this.values.set(input.Key!, Uint8Array.from(input.Body as Uint8Array));
- }
- async get(input: Parameters<S3ObjectClient["get"]>[0]): Promise<Uint8Array | undefined> {
- const value = this.values.get(input.Key!);
- return value === undefined ? undefined : Uint8Array.from(value);
- }
-}
-
-async function ffmpegAvailable(): Promise<boolean> {
- try {
- await run("ffmpeg", ["-version"]);
- await run("ffprobe", ["-version"]);
- return true;
- } catch {
- return false;
- }
-}
-
-test("the function answers a real Need with real media, over a bucket it addresses like the store does",
- { skip: (await ffmpegAvailable()) ? false : "ffmpeg and ffprobe are not on PATH" },
- async () => {
- const work = await mkdtemp(join(tmpdir(), "hypit-media-lambda-"));
- try {
- // One second of real audio, so ffprobe has something true to report.
- const path = join(work, "source.wav");
- await run("ffmpeg", ["-y", "-f", "lavfi", "-i", "sine=frequency=440:duration=1",
- "-c:a", "pcm_s16le", "-ar", "48000", "-ac", "2", path]);
- const bytes = await readFile(path);
- const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}` as Digest;
-
- const bucket = new Bucket();
- // Placed at the key the ArtifactStore would have used — the shared law.
- bucket.values.set(s3ArtifactKey("svml", digest), Uint8Array.from(bytes));
-
- const handle = createMediaLambdaHandler({ client: bucket, ffmpegPath: "ffmpeg", ffprobePath: "ffprobe" });
- const reply = await handle({
- contract: "hypit.media-lambda-request@1",
- operation: "inspect",
- artifacts: { bucket: "fixture", prefix: "svml" },
- constraints: {
- source: { kind: "blob", digest, size: bytes.byteLength, mediaType: "audio/wav" },
- },
- }) as Record<string, unknown>;
-
- assert.equal(reply.ok, true, `the function failed: ${JSON.stringify(reply)}`);
- assert.equal(reply.operation, "inspect");
- const stored = reply.value as { kind: string; value: { streams: { kind: string; sampleRate: number }[] } };
- assert.equal(stored.kind, "inline");
- const value = stored.value;
- assert.equal(value.streams.length, 1);
- assert.equal(value.streams[0]!.kind, "audio");
- assert.equal(value.streams[0]!.sampleRate, 48_000);
- assert.equal("metadata" in reply, false);
- } finally {
- await rm(work, { recursive: true, force: true });
- }
- });
-
-test("a source the bucket does not hold is a typed failure, never a throw", async () => {
- const handle = createMediaLambdaHandler({ client: new Bucket() });
- const reply = await handle({
- contract: "hypit.media-lambda-request@1",
- operation: "inspect",
- artifacts: { bucket: "fixture" },
- constraints: {
- source: { kind: "blob", digest: `sha256:${"0".repeat(64)}`, size: 1, mediaType: "audio/wav" },
- },
- }) as Record<string, unknown>;
- assert.equal(reply.ok, false);
- assert.equal(reply.code, "MEDIA_OPERATION_FAILED");
- assert.match(String(reply.message), /is unavailable/u);
-});
-
-test("an envelope from another contract is refused before any media is touched", async () => {
- const handle = createMediaLambdaHandler({ client: new Bucket() });
- const reply = await handle({ contract: "hypit.media-lambda-request@invalid" }) as Record<string, unknown>;
- assert.equal(reply.ok, false);
- assert.match(String(reply.message), /contract must be hypit\.media-lambda-request@1/u);
-});
-
-test("a Layer that lies about its FFmpeg version fails before reading an Artifact",
- { skip: (await ffmpegAvailable()) ? false : "ffmpeg and ffprobe are not on PATH" },
- async () => {
- const handle = createMediaLambdaHandler({
- client: new Bucket(),
- ffmpegPath: "ffmpeg",
- ffprobePath: "ffprobe",
- expectedFfmpegVersion: "0.0.0-impossible",
- });
- const reply = await handle({
- contract: "hypit.media-lambda-request@1",
- operation: "inspect",
- artifacts: { bucket: "fixture" },
- constraints: {
- source: {
- kind: "blob",
- digest: `sha256:${"0".repeat(64)}`,
- size: 1,
- mediaType: "audio/wav",
- },
- },
- }) as Record<string, unknown>;
- assert.equal(reply.ok, false);
- assert.match(String(reply.message), /Layer mismatch: expected 0\.0\.0-impossible/u);
- });
diff --git a/test/fixture-digest.ts b/test/fixture-digest.ts
deleted file mode 100644
index 6a835e49..00000000
--- a/test/fixture-digest.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import type { Digest } from "@hypit/protocol";
-
-/** Test-only Blob address. It encodes fixture text; it does not hash program meaning. */
-export function fixtureDigest(value: unknown): Digest {
- const text = typeof value === "string" ? value : JSON.stringify(value);
- const bytes = new TextEncoder().encode(text);
- const hex = [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
- return `sha256:${hex.slice(0, 64).padEnd(64, "0")}`;
-}
diff --git a/test/fixture-resource.ts b/test/fixture-resource.ts
new file mode 100644
index 00000000..9b74c3d3
--- /dev/null
+++ b/test/fixture-resource.ts
@@ -0,0 +1,8 @@
+import type { ResourceId } from "@hypit/protocol";
+
+/** Test-only resource identity. It is readable and intentionally unrelated to byte content. */
+export function fixtureResource(value: unknown): ResourceId {
+ const text = typeof value === "string" ? value : JSON.stringify(value);
+ const safe = text.replace(/[^a-zA-Z0-9._:-]+/gu, "_").replace(/^_+|_+$/gu, "");
+ return `res_fixture:${safe.length === 0 ? "value" : safe}`;
+}
diff --git a/test/semantic-track-fixture.ts b/test/semantic-track-fixture.ts
index 31858c6e..a26513b5 100644
--- a/test/semantic-track-fixture.ts
+++ b/test/semantic-track-fixture.ts
@@ -13,7 +13,7 @@ type FixtureAnchor = {
const audioArtifact = {
kind: "blob" as const,
- digest: `sha256:${"0".repeat(64)}` as const,
+ resource: "res_semantic-track-fixture" as const,
size: 1,
mediaType: "audio/wav",
};
diff --git a/tsconfig.json b/tsconfig.json
index c95290a0..57a069fa 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -20,8 +20,7 @@
"include": [
"packages/**/*.ts",
"examples/*/packages/*/src/**/*.ts",
- "examples/*/packages/*/test/**/*.ts",
- "services/media-lambda/src/**/*.ts"
+ "examples/*/packages/*/test/**/*.ts"
],
"exclude": [
"dist",