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: make compiler workspace replaceable

kashorina971b79d1651
diff --git a/packages/cli/src/main.ts b/packages/cli/src/main.ts
index aed63e2d..fbac9f30 100644
--- a/packages/cli/src/main.ts
+++ b/packages/cli/src/main.ts
@@ -225,7 +225,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>
moduleClosure: result.program.closure.digest,
graph: result.elaboration.graph.id,
units: result.closure.units.length,
- sourceAssets: result.sourceArtifacts.map((item) => item.artifact),
+ sourceAssets: result.attachments.map((item) => item.artifact),
modules: result.program.closure.modules.map((item) => `${item.ref.name}@${item.ref.version}`),
exports: result.exports.map((item) => ({ name: item.name, type: item.type, kind: item.ref.kind })),
}, null, 2)}\n`);
@@ -243,7 +243,7 @@ export async function runCli(argv: readonly string[], io: CliIo): Promise<void>
const built = await runtime.build({
id: args.buildId ?? result.state.id,
state: result.state,
- sourceArtifacts: result.compilation.sourceArtifacts,
+ attachments: result.compilation.attachments,
}, {
follow: args.follow,
...(args.maxWaitMs === undefined ? {} : { maxWaitMs: args.maxWaitMs }),
diff --git a/packages/compiler-node/README.md b/packages/compiler-node/README.md
index 721b940c..3666dd0a 100644
--- a/packages/compiler-node/README.md
+++ b/packages/compiler-node/README.md
@@ -2,8 +2,8 @@
Domain-neutral Node.js compiler host for v2.
-This package is outside Core. It owns the environmental work required to turn a real file into the
-already implemented compiler IR:
+This package is outside Core. It connects a replaceable definition-time `Workspace` to the already
+implemented compiler IR:
```text
file + registered Frontends + registered manifests
@@ -18,15 +18,16 @@ their digest-bound dependencies. It does not install npm packages or execute mod
embedding application must register the manifests and matching Frontend/Surface implementations it
has chosen to trust.
-`NodeSourceHost` is the filesystem authority. It accepts only relative recursive Source imports,
-canonicalizes real paths, confines reads to one declared root, rejects symlink escapes and locks
-each import edge to the first bytes read for the whole compilation. Source paths are diagnostics and
-cache keys; Source Closure semantic identity still depends on content rather than machine location.
+`NodeCompiler` accepts the host-neutral `Workspace` contract. With no explicit Workspace it creates
+the convenient `@svml/workspace-fs-node` default: relative recursive Source imports are confined to
+one canonical root, symlink escapes are rejected and each edge is locked to the first bytes read for
+that compilation. A browser, Git, memory or remote Host can inject another Workspace without
+changing Frontends, Surfaces, Source Closure identity or Core.
-The same Host owns a separate Source Asset capability. A Frontend/Surface may request a relative
-asset and assign its exact media type, but it never receives a path or filesystem handle. The Host
-reads each canonical asset once, rejects root and symlink escapes, returns a `BlobRef`, binds that
-reference into the requesting SourceUnit and exposes defensive byte attachments on the Node
+The Workspace session owns a separate Source Asset capability. A Frontend/Surface may request an
+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.
@@ -40,7 +41,8 @@ the ordinary Elaborator Source Closure implementation. `planFile()` resolves aut
names to Logical Outputs and asks Core to derive the finite reverse-demand plan.
The package contains no Script, video, Provider, queue, credentials or rendering knowledge. A
-non-video application can use it with only its own manifests, Frontends and Surfaces.
+non-video application can use it with only its own manifests, Frontends, Surfaces and chosen
+Workspace implementation.
Package installation, lockfile-based third-party code loading and sandbox execution remain Host
features above this registry; treating an import string as permission to execute npm code would
diff --git a/packages/compiler-node/package.json b/packages/compiler-node/package.json
index d326d346..147905e2 100644
--- a/packages/compiler-node/package.json
+++ b/packages/compiler-node/package.json
@@ -9,8 +9,10 @@
"dependencies": {
"@svml/core": "workspace:*",
"@svml/elaborator": "workspace:*",
+ "@svml/host": "workspace:*",
"@svml/protocol": "workspace:*",
- "@svml/validation": "workspace:*"
+ "@svml/validation": "workspace:*",
+ "@svml/workspace-fs-node": "workspace:*"
},
"devDependencies": {
"@svml/text": "workspace:*"
diff --git a/packages/compiler-node/src/compiler.ts b/packages/compiler-node/src/compiler.ts
index ad264193..7ad99853 100644
--- a/packages/compiler-node/src/compiler.ts
+++ b/packages/compiler-node/src/compiler.ts
@@ -1,4 +1,4 @@
-import { dirname, resolve } from "node:path";
+import { resolve } from "node:path";
import {
sealBuildRequest,
@@ -15,6 +15,7 @@ import type {
CompiledSourceClosure,
AuthorRecordAdmitter,
} from "@svml/elaborator";
+import type { ArtifactAttachment, Workspace, WorkspaceSession } from "@svml/host";
import type {
BuildPlan,
BuildRequest,
@@ -27,11 +28,10 @@ import {
createRecordAdmitter,
} from "@svml/validation";
import type { TypeValidatorRegistryLike } from "@svml/validation";
+import { NodeFilesystemWorkspace } from "@svml/workspace-fs-node";
import { NodeCompilerError } from "./error.js";
import type { ModulePackageRegistryLike } from "./modules.js";
-import { NodeSourceHost } from "./source.js";
-import type { NodeSourceArtifact } from "./source.js";
type DiscoveredUnit = {
readonly source: AuthorSourceUnit;
@@ -43,7 +43,7 @@ async function discoverClosure(
entry: AuthorSourceUnit,
frontendId: string,
frontends: AuthorFrontendRegistryLike,
- sources: NodeSourceHost,
+ workspace: WorkspaceSession,
): Promise<readonly DiscoveredUnit[]> {
const units = new Map<string, DiscoveredUnit>();
const visiting = new Set<string>();
@@ -60,7 +60,7 @@ async function discoverClosure(
visiting.add(key);
const discovery = await frontend.discover(source);
for (const request of discovery.sources) {
- await visit(await sources.resolveSource(source, request), request.frontend);
+ await visit(await workspace.resolveSource(source, request), request.frontend);
}
visiting.delete(key);
units.set(key, { source, frontend: selectedFrontend, discovery });
@@ -75,6 +75,8 @@ export type NodeCompilerOptions = {
readonly entryFrontend: string;
/** Files reachable through source imports must resolve inside this root. Defaults to entry dirname. */
readonly root?: string;
+ /** Replaces the default Node filesystem definition environment. */
+ readonly workspace?: Workspace;
/** Trusted Type-owner validators used to admit authored Records before linking. */
readonly validators?: TypeValidatorRegistryLike;
/** Low-level Host hook for a sandboxed or remote admission implementation. */
@@ -97,7 +99,7 @@ export type PlannedSource = {
export type NodeCompiledSourceClosure = CompiledSourceClosure & {
/** Host-side transfer bundle; bytes are not serialized into Core BuildState. */
- readonly sourceArtifacts: readonly NodeSourceArtifact[];
+ readonly attachments: readonly ArtifactAttachment[];
};
/** Domain-neutral Node facade from a real source file to a verified Source Closure or BuildPlan. */
@@ -112,20 +114,29 @@ export class NodeCompiler {
"NodeCompiler accepts validators or a custom Record admitter, not both",
);
}
+ if (options.workspace !== undefined && options.root !== undefined) {
+ throw new NodeCompilerError(
+ "AMBIGUOUS_WORKSPACE",
+ "NodeCompiler accepts a Workspace or the root option for its default filesystem Workspace, not both",
+ );
+ }
this.#options = options;
this.#admitRecord = options.admitRecord
?? createRecordAdmitter(options.validators ?? new TypeValidatorRegistry());
}
async compileFile(file: string): Promise<NodeCompiledSourceClosure> {
- const entryPath = resolve(file);
- const sources = await NodeSourceHost.create(this.#options.root ?? dirname(entryPath));
- const entry = await sources.load(entryPath);
+ const workspace = this.#options.workspace === undefined
+ ? await new NodeFilesystemWorkspace({
+ ...(this.#options.root === undefined ? {} : { root: this.#options.root }),
+ }).open(resolve(file))
+ : await this.#options.workspace.open(file);
+ const entry = workspace.entry;
const discovered = await discoverClosure(
entry,
this.#options.entryFrontend,
this.#options.frontends,
- sources,
+ workspace,
);
const closure = this.#options.modules.createClosure(
discovered.flatMap((unit) => unit.discovery.modules),
@@ -135,11 +146,11 @@ export class NodeCompiler {
frontend: this.#options.entryFrontend,
closure,
frontends: this.#options.frontends,
- resolveSource: sources.resolveSource,
- resolveAsset: sources.resolveAsset,
+ resolveSource: workspace.resolveSource,
+ resolveAsset: workspace.resolveAsset,
admitRecord: this.#admitRecord,
});
- return { ...compilation, sourceArtifacts: sources.sourceArtifacts() };
+ return { ...compilation, attachments: await workspace.attachments() };
}
async planFile(file: string, options: PlanFileOptions): Promise<PlannedSource> {
diff --git a/packages/compiler-node/src/index.ts b/packages/compiler-node/src/index.ts
index 542abd26..08c5c82a 100644
--- a/packages/compiler-node/src/index.ts
+++ b/packages/compiler-node/src/index.ts
@@ -6,8 +6,6 @@ export type {
ModulePackageRegistryLike,
RegisteredModulePackage,
} from "./modules.js";
-export { NodeSourceHost } from "./source.js";
-export type { NodeSourceArtifact } from "./source.js";
export { NodeCompiler } from "./compiler.js";
export type {
NodeCompilerOptions,
diff --git a/packages/compiler-node/test/compiler.test.ts b/packages/compiler-node/test/compiler.test.ts
index 61c77fec..526b38e3 100644
--- a/packages/compiler-node/test/compiler.test.ts
+++ b/packages/compiler-node/test/compiler.test.ts
@@ -1,4 +1,5 @@
import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
import {
mkdtemp,
mkdir,
@@ -14,7 +15,6 @@ import {
ModulePackageRegistry,
NodeCompiler,
NodeCompilerError,
- NodeSourceHost,
} from "@svml/compiler-node";
import {
computeModuleDigest,
@@ -26,16 +26,25 @@ import {
verifySourceClosure,
} from "@svml/elaborator";
import type {
+ AuthorSourceAssetRequest,
+ AuthorSourceImport,
+ AuthorSourceUnit,
+} from "@svml/elaborator";
+import type {
+ BlobRef,
ModuleManifest,
ModuleRef,
ProducerRef,
TypeRef,
} from "@svml/protocol";
+import type { Workspace } from "@svml/host";
+import { WorkspaceError } from "@svml/host";
import {
createTextAuthorFrontend,
TextSurfaceRegistry,
textAuthorFrontendId,
} from "@svml/text";
+import { NodeFilesystemWorkspace } from "@svml/workspace-fs-node";
function emptyManifest(name: string, version = "1"): ModuleManifest {
return {
@@ -198,7 +207,7 @@ function compiler(root: string): NodeCompiler {
return new NodeCompiler({ modules, frontends, entryFrontend: textAuthorFrontendId, root });
}
-function assetCompiler(root: string): NodeCompiler {
+function assetCompiler(environment: { readonly root: string } | { readonly workspace: Workspace }): NodeCompiler {
const modules = new ModulePackageRegistry();
modules.register({ manifest: assetManifest });
const surfaces = new TextSurfaceRegistry();
@@ -222,7 +231,41 @@ function assetCompiler(root: string): NodeCompiler {
return resolved;
},
}));
- return new NodeCompiler({ modules, frontends, entryFrontend: textAuthorFrontendId, root });
+ return new NodeCompiler({ modules, frontends, entryFrontend: textAuthorFrontendId, ...environment });
+}
+
+function memoryWorkspace(sourceText: string, assetBytes: Uint8Array): Workspace {
+ return {
+ async open(entryLocator) {
+ const entry: AuthorSourceUnit = { id: entryLocator, name: "main.svml", text: sourceText };
+ let attachment: { readonly artifact: BlobRef; readonly bytes: Uint8Array } | undefined;
+ return {
+ entry,
+ async resolveSource(_importer: AuthorSourceUnit, request: AuthorSourceImport) {
+ throw new WorkspaceError("UNKNOWN_MEMORY_SOURCE", `No memory source satisfies ${request.from}`, request.from);
+ },
+ async resolveAsset(importer: AuthorSourceUnit, request: AuthorSourceAssetRequest) {
+ if (importer !== entry || request.from !== "./reference.bin") {
+ throw new WorkspaceError("UNKNOWN_MEMORY_ASSET", `No memory asset satisfies ${request.from}`, request.from);
+ }
+ const bytes = Uint8Array.from(assetBytes);
+ const artifact: BlobRef = {
+ kind: "blob",
+ digest: `sha256:${createHash("sha256").update(bytes).digest("hex")}`,
+ size: bytes.byteLength,
+ mediaType: request.mediaType,
+ };
+ attachment = { artifact, bytes };
+ return { artifact: { ...artifact } };
+ },
+ attachments() {
+ return attachment === undefined
+ ? []
+ : [{ artifact: { ...attachment.artifact }, bytes: Uint8Array.from(attachment.bytes) }];
+ },
+ };
+ },
+ };
}
test("Node Compiler discovers real imports and plans a named public export", async () => {
@@ -253,9 +296,9 @@ test("source assets are content addressed, closure-bound and returned as a Host
</svml>`, "utf8");
await writeFile(asset, new Uint8Array([1, 2, 3, 4]));
- const first = await assetCompiler(root).compileFile(file);
+ const first = await assetCompiler({ root }).compileFile(file);
const unit = first.closure.units.find((item) => item.assets.length > 0);
- const attachment = first.sourceArtifacts[0];
+ const attachment = first.attachments[0];
assert.equal(unit?.assets[0]?.from, "./reference.bin");
assert.equal(unit?.assets[0]?.artifact.digest, attachment?.artifact.digest);
assert.deepEqual(attachment?.bytes, new Uint8Array([1, 2, 3, 4]));
@@ -276,47 +319,75 @@ test("source assets are content addressed, closure-bound and returned as a Host
);
await writeFile(asset, new Uint8Array([9, 8, 7]));
- const second = await assetCompiler(root).compileFile(file);
+ const second = await assetCompiler({ root }).compileFile(file);
assert.notEqual(second.closure.id, first.closure.id);
- assert.notEqual(second.sourceArtifacts[0]?.artifact.digest, attachment?.artifact.digest);
+ assert.notEqual(second.attachments[0]?.artifact.digest, attachment?.artifact.digest);
});
-test("Node Source Host contains symlinks and reads each canonical source only once", async () => {
+test("filesystem Workspace contains symlinks and reads each canonical source only once", async () => {
const parent = await mkdtemp(join(tmpdir(), "svml-source-host-"));
const root = join(parent, "project");
await mkdir(root);
const entryPath = join(root, "main.svml");
+ const includedPath = join(root, "included.svs");
const outsidePath = join(parent, "outside.svs");
const assetPath = join(root, "asset.bin");
await writeFile(entryPath, "first", "utf8");
+ await writeFile(includedPath, "included-first", "utf8");
await writeFile(outsidePath, "outside", "utf8");
await writeFile(assetPath, new Uint8Array([1, 2, 3]));
await symlink(outsidePath, join(root, "escaped.svs"));
- const host = await NodeSourceHost.create(root);
- const entry = await host.load(entryPath);
+ const workspace = await new NodeFilesystemWorkspace({ root }).open(entryPath);
+ const entry = workspace.entry;
await writeFile(entryPath, "second", "utf8");
- assert.equal((await host.load(entryPath)).text, "first");
+ assert.equal((await new NodeFilesystemWorkspace({ root }).open(entryPath)).entry.text, "second");
+ assert.equal(entry.text, "first");
assert.equal(await readFile(entryPath, "utf8"), "second");
- const firstAsset = await host.resolveAsset(entry, { from: "./asset.bin", mediaType: "application/octet-stream" });
+ const sourceRequest = { from: "./included.svs", alias: "included", frontend: "example.frontend@1" };
+ const firstIncluded = await workspace.resolveSource(entry, sourceRequest);
+ await writeFile(includedPath, "included-second", "utf8");
+ assert.deepEqual(await workspace.resolveSource(entry, sourceRequest), firstIncluded);
+ assert.equal(firstIncluded.text, "included-first");
+ const firstAsset = await workspace.resolveAsset(entry, { from: "./asset.bin", mediaType: "application/octet-stream" });
await writeFile(assetPath, new Uint8Array([4, 5, 6, 7]));
- const lockedAsset = await host.resolveAsset(entry, { from: "./asset.bin", mediaType: "application/octet-stream" });
+ const lockedAsset = await workspace.resolveAsset(entry, { from: "./asset.bin", mediaType: "application/octet-stream" });
assert.deepEqual(lockedAsset, firstAsset, "one Host locks an asset edge to the first bytes read");
- const detached = host.sourceArtifacts();
+ const detached = await workspace.attachments();
detached[0]?.bytes.fill(0);
- assert.deepEqual(host.sourceArtifacts()[0]?.bytes, new Uint8Array([1, 2, 3]));
+ assert.deepEqual((await workspace.attachments())[0]?.bytes, new Uint8Array([1, 2, 3]));
await assert.rejects(
- async () => await host.resolveSource(entry, {
+ async () => await workspace.resolveSource(entry, {
from: "./escaped.svs",
alias: "escaped",
frontend: "example.frontend@1",
}),
- (error: unknown) => error instanceof NodeCompilerError && error.code === "SOURCE_OUTSIDE_ROOT",
+ (error: unknown) => error instanceof WorkspaceError && error.code === "SOURCE_OUTSIDE_ROOT",
);
await assert.rejects(
- async () => await host.resolveAsset(entry, {
+ async () => await workspace.resolveAsset(entry, {
from: "./escaped.svs",
mediaType: "application/octet-stream",
}),
- (error: unknown) => error instanceof NodeCompilerError && error.code === "SOURCE_ASSET_OUTSIDE_ROOT",
+ (error: unknown) => error instanceof WorkspaceError && error.code === "SOURCE_ASSET_OUTSIDE_ROOT",
);
});
+
+test("filesystem and in-memory Workspaces compile identical source and bytes to one semantic result", async () => {
+ const root = await mkdtemp(join(tmpdir(), "svml-workspace-equivalence-"));
+ const file = join(root, "main.svml");
+ const source = `<svml>
+ <import as="asset" from="example.asset-lab@1"/>
+ <asset:Asset id="reference" src="./reference.bin"/>
+ </svml>`;
+ const bytes = new Uint8Array([3, 1, 4, 1, 5]);
+ await writeFile(file, source, "utf8");
+ await writeFile(join(root, "reference.bin"), bytes);
+
+ const filesystem = await assetCompiler({ root }).compileFile(file);
+ const memory = await assetCompiler({ workspace: memoryWorkspace(source, bytes) }).compileFile("memory:main");
+
+ assert.equal(memory.closure.id, filesystem.closure.id);
+ assert.equal(memory.module.semanticDigest, filesystem.module.semanticDigest);
+ assert.equal(memory.elaboration.graph.id, filesystem.elaboration.graph.id);
+ assert.deepEqual(memory.attachments, filesystem.attachments);
+});
diff --git a/packages/host/README.md b/packages/host/README.md
new file mode 100644
index 00000000..de4dddcc
--- /dev/null
+++ b/packages/host/README.md
@@ -0,0 +1,10 @@
+# `@svml/host`
+
+Domain-neutral contracts for concrete environments surrounding Core. This package currently owns
+only the definition-time `Workspace` session and generic `ArtifactAttachment` transfer envelope.
+It contains no filesystem, parser, scheduler, store, Provider or domain implementation.
+
+A `Workspace` opens one isolated compilation session. The session supplies one entry SourceUnit,
+relative Source/Asset resolution and the exact content-addressed bytes requested while decoding.
+Filesystem, browser, Git, memory and remote workspaces implement the same interface. Compiler and
+Runtime never infer environment selection from author imports.
diff --git a/packages/host/package.json b/packages/host/package.json
new file mode 100644
index 00000000..f9444eaf
--- /dev/null
+++ b/packages/host/package.json
@@ -0,0 +1,13 @@
+{
+ "name": "@svml/host",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/elaborator": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ }
+}
diff --git a/packages/host/src/index.ts b/packages/host/src/index.ts
new file mode 100644
index 00000000..bcb8e6af
--- /dev/null
+++ b/packages/host/src/index.ts
@@ -0,0 +1,38 @@
+import type {
+ AuthorSourceAssetResolver,
+ AuthorSourceResolver,
+ AuthorSourceUnit,
+ Awaitable,
+} from "@svml/elaborator";
+import type { BlobRef } from "@svml/protocol";
+
+/** Host transfer bytes. Their origin is deliberately absent from the Runtime contract. */
+export type ArtifactAttachment = {
+ readonly artifact: BlobRef;
+ readonly bytes: Uint8Array;
+};
+
+/** One isolated, read-once definition session for exactly one compilation. */
+export interface WorkspaceSession {
+ readonly entry: AuthorSourceUnit;
+ readonly resolveSource: AuthorSourceResolver;
+ readonly resolveAsset: AuthorSourceAssetResolver;
+ attachments(): Awaitable<readonly ArtifactAttachment[]>;
+}
+
+/** Replaceable definition environment: filesystem, browser, Git, memory or remote workspace. */
+export interface Workspace {
+ open(entryLocator: string): Awaitable<WorkspaceSession>;
+}
+
+export class WorkspaceError extends Error {
+ readonly code: string;
+ readonly subject: string | undefined;
+
+ constructor(code: string, message: string, subject?: string) {
+ super(message);
+ this.name = "WorkspaceError";
+ this.code = code;
+ this.subject = subject;
+ }
+}
diff --git a/packages/local/README.md b/packages/local/README.md
index dc06f3b5..76f663fc 100644
--- a/packages/local/README.md
+++ b/packages/local/README.md
@@ -45,9 +45,10 @@ Endpoint implementation and lane, not the `.svml` author document.
advanced hosts may call `createLocalRuntime` with Postgres or other implementations of the same
ports instead of using the project defaults.
-`LocalBuildRequest.sourceArtifacts` is the explicit ingress from a Compiler Host into the selected
+`LocalBuildRequest.attachments` is the explicit ingress from a trusted Host into the selected
ArtifactStore. Each attachment carries claimed `BlobRef` metadata plus bytes; Local Runtime copies
the bytes, stores them content-addressably and requires the Store's returned digest, size and media
type to match before any Core command can consume the reference. Attachments never enter
-BuildState, SQLite or author source. Reusing a Build after restart needs no reattachment when the
+BuildState, SQLite or author source, and Runtime does not know whether they came from source assets,
+an upload, a provided Candidate, Git or an API. Reusing a Build after restart needs no reattachment when the
chosen durable ArtifactStore still contains those digests.
diff --git a/packages/local/package.json b/packages/local/package.json
index bdd59b3d..6745554c 100644
--- a/packages/local/package.json
+++ b/packages/local/package.json
@@ -10,6 +10,7 @@
"@svml/artifact-store-fs": "workspace:*",
"@svml/component-kit": "workspace:*",
"@svml/credential-store-env": "workspace:*",
+ "@svml/host": "workspace:*",
"@svml/driver-node": "workspace:*",
"@svml/package-loader-node": "workspace:*",
"@svml/protocol": "workspace:*",
diff --git a/packages/local/src/runtime.ts b/packages/local/src/runtime.ts
index dfcb3699..9e175f34 100644
--- a/packages/local/src/runtime.ts
+++ b/packages/local/src/runtime.ts
@@ -190,8 +190,8 @@ export async function createLocalRuntime(
...(options.scheduling ?? {}),
buildStore: options.buildStore,
});
- const stageSourceArtifacts = async (request: LocalBuildRequest): Promise<void> => {
- for (const item of request.sourceArtifacts ?? []) {
+ const stageAttachments = async (request: LocalBuildRequest): Promise<void> => {
+ for (const item of request.attachments ?? []) {
const stored = await options.artifactStore.put(Uint8Array.from(item.bytes), item.artifact.mediaType);
assert(
stored.digest === item.artifact.digest
@@ -206,7 +206,7 @@ export async function createLocalRuntime(
request: LocalBuildRequest,
follow: LocalBuildOptions = {},
) => {
- await stageSourceArtifacts(request);
+ await stageAttachments(request);
const startedAt = Date.now();
const pollIntervalMs = nonNegativeInteger(follow.pollIntervalMs ?? 1_000, "pollIntervalMs");
const maxWaitMs = follow.maxWaitMs === undefined
@@ -228,7 +228,7 @@ export async function createLocalRuntime(
return {
build: runBuild,
async buildMany(requests) {
- await Promise.all(requests.map(stageSourceArtifacts));
+ await Promise.all(requests.map(stageAttachments));
return await scheduler.run(requests.map(scheduled));
},
async status(build) {
diff --git a/packages/local/src/types.ts b/packages/local/src/types.ts
index 510d9c7c..e76aeaa3 100644
--- a/packages/local/src/types.ts
+++ b/packages/local/src/types.ts
@@ -1,9 +1,7 @@
import type { Awaitable, ComponentPackage } from "@svml/component-kit";
+import type { ArtifactAttachment } from "@svml/host";
import type { NodeProviderPackage } from "@svml/provider-kit";
-import type {
- BlobRef,
- BuildState,
-} from "@svml/protocol";
+import type { BuildState } from "@svml/protocol";
import type {
ArtifactStore,
BuildSnapshot,
@@ -81,12 +79,7 @@ export type LocalBuildRequest = {
readonly id: string;
readonly state: BuildState;
/** Host transfer bundle. It is staged before Core commands run and never enters BuildState. */
- readonly sourceArtifacts?: readonly LocalSourceArtifact[];
-};
-
-export type LocalSourceArtifact = {
- readonly artifact: BlobRef;
- readonly bytes: Uint8Array;
+ readonly attachments?: readonly ArtifactAttachment[];
};
export type LocalBuildOptions = {
diff --git a/packages/local/test/local.test.ts b/packages/local/test/local.test.ts
index 119287a0..d5e6763f 100644
--- a/packages/local/test/local.test.ts
+++ b/packages/local/test/local.test.ts
@@ -321,7 +321,7 @@ test("project local runtime accepts a permission-checked replacement ArtifactSto
runtime.build({
id: "source-artifact-staging",
state: createGreetingBuild(),
- sourceArtifacts: [{ artifact: sourceArtifact, bytes }],
+ attachments: [{ artifact: sourceArtifact, bytes }],
}),
/does not bind demanded capability/u,
);
@@ -330,7 +330,7 @@ test("project local runtime accepts a permission-checked replacement ArtifactSto
runtime.build({
id: "tampered-source-artifact",
state: createGreetingBuild(),
- sourceArtifacts: [{ artifact: sourceArtifact, bytes: new Uint8Array([0]) }],
+ attachments: [{ artifact: sourceArtifact, bytes: new Uint8Array([0]) }],
}),
/does not match its staged bytes/u,
);
diff --git a/packages/package-loader-node/package.json b/packages/package-loader-node/package.json
index 7f372fc6..a1f3a0b8 100644
--- a/packages/package-loader-node/package.json
+++ b/packages/package-loader-node/package.json
@@ -10,6 +10,7 @@
"@svml/component-kit": "workspace:*",
"@svml/compiler-node": "workspace:*",
"@svml/elaborator": "workspace:*",
+ "@svml/host": "workspace:*",
"@svml/protocol": "workspace:*",
"@svml/text": "workspace:*",
"@svml/validation": "workspace:*"
diff --git a/packages/package-loader-node/src/activation.ts b/packages/package-loader-node/src/activation.ts
index 3f63bbfd..9cc0cc98 100644
--- a/packages/package-loader-node/src/activation.ts
+++ b/packages/package-loader-node/src/activation.ts
@@ -12,6 +12,7 @@ import {
} from "@svml/compiler-node";
import type { RegisteredModulePackage } from "@svml/compiler-node";
import { AuthorFrontendRegistry } from "@svml/elaborator";
+import type { Workspace } from "@svml/host";
import { isDigest } from "@svml/protocol";
import {
createTextAuthorFrontend,
@@ -25,6 +26,7 @@ import type { NodePackageActivation } from "./types.js";
export type CreateActivatedNodeCompilerOptions = {
readonly root?: string;
+ readonly workspace?: Workspace;
};
function assertPackage(value: NodePackageActivation): void {
@@ -166,5 +168,6 @@ export function createActivatedNodeCompiler(
validators,
entryFrontend: textAuthorFrontendId,
...(options.root === undefined ? {} : { root: options.root }),
+ ...(options.workspace === undefined ? {} : { workspace: options.workspace }),
});
}
diff --git a/packages/workspace-fs-node/README.md b/packages/workspace-fs-node/README.md
new file mode 100644
index 00000000..58930010
--- /dev/null
+++ b/packages/workspace-fs-node/README.md
@@ -0,0 +1,8 @@
+# `@svml/workspace-fs-node`
+
+Default Node filesystem implementation of the host-neutral `Workspace` contract.
+
+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
+Frontend, package, Core, Runtime, Provider or domain knowledge.
diff --git a/packages/workspace-fs-node/package.json b/packages/workspace-fs-node/package.json
new file mode 100644
index 00000000..43db6028
--- /dev/null
+++ b/packages/workspace-fs-node/package.json
@@ -0,0 +1,14 @@
+{
+ "name": "@svml/workspace-fs-node",
+ "version": "0.0.0-dev",
+ "private": true,
+ "type": "module",
+ "exports": {
+ ".": "./src/index.ts"
+ },
+ "dependencies": {
+ "@svml/elaborator": "workspace:*",
+ "@svml/host": "workspace:*",
+ "@svml/protocol": "workspace:*"
+ }
+}
diff --git a/packages/workspace-fs-node/src/index.ts b/packages/workspace-fs-node/src/index.ts
new file mode 100644
index 00000000..255b91a9
--- /dev/null
+++ b/packages/workspace-fs-node/src/index.ts
@@ -0,0 +1,2 @@
+export { NodeFilesystemWorkspace } from "./workspace.js";
+export type { NodeFilesystemWorkspaceOptions } from "./workspace.js";
diff --git a/packages/compiler-node/src/source.ts b/packages/workspace-fs-node/src/workspace.ts
similarity index 54%
rename from packages/compiler-node/src/source.ts
rename to packages/workspace-fs-node/src/workspace.ts
index 3bda85cf..71e8b5c5 100644
--- a/packages/compiler-node/src/source.ts
+++ b/packages/workspace-fs-node/src/workspace.ts
@@ -3,102 +3,120 @@ import { readFile, realpath } from "node:fs/promises";
import { dirname, isAbsolute, relative, resolve } from "node:path";
import type {
- AuthorSourceImport,
- AuthorSourceAssetResolver,
AuthorSourceAssetRequest,
- AuthorSourceResolver,
+ AuthorSourceImport,
AuthorSourceUnit,
} from "@svml/elaborator";
+import type {
+ ArtifactAttachment,
+ Workspace,
+ WorkspaceSession,
+} from "@svml/host";
+import { WorkspaceError } from "@svml/host";
import type { BlobRef } from "@svml/protocol";
-import { NodeCompilerError } from "./error.js";
-
function isWithin(root: string, path: string): boolean {
const relation = relative(root, path);
return relation === "" || (!relation.startsWith("..") && !isAbsolute(relation));
}
-/** One-build, read-once filesystem authority for SourceUnits. */
-export class NodeSourceHost {
+class NodeFilesystemWorkspaceSession implements WorkspaceSession {
readonly root: string;
- readonly #cache = new Map<string, AuthorSourceUnit>();
- readonly #edges = new Map<string, AuthorSourceUnit>();
+ readonly entry: AuthorSourceUnit;
+ readonly #sourceCache = new Map<string, AuthorSourceUnit>();
+ readonly #sourceEdges = new Map<string, AuthorSourceUnit>();
readonly #assetBytes = new Map<string, Uint8Array>();
readonly #assetEdges = new Map<string, string>();
- readonly #attachments = new Map<string, NodeSourceArtifact>();
+ readonly #attachments = new Map<string, ArtifactAttachment>();
- private constructor(root: string) {
+ private constructor(root: string, entry: AuthorSourceUnit) {
this.root = root;
+ this.entry = entry;
+ this.#sourceCache.set(entry.id, entry);
}
- static async create(root: string): Promise<NodeSourceHost> {
- return new NodeSourceHost(await realpath(resolve(root)));
+ static async open(rootLocator: string, entryLocator: string): Promise<NodeFilesystemWorkspaceSession> {
+ const root = await realpath(resolve(rootLocator));
+ const canonicalEntry = await realpath(resolve(entryLocator));
+ if (!isWithin(root, canonicalEntry)) {
+ throw new WorkspaceError(
+ "SOURCE_OUTSIDE_ROOT",
+ `Source ${canonicalEntry} is outside workspace root ${root}`,
+ canonicalEntry,
+ );
+ }
+ const entry: AuthorSourceUnit = {
+ id: canonicalEntry,
+ name: relative(root, canonicalEntry) || canonicalEntry.split("/").at(-1) || canonicalEntry,
+ text: await readFile(canonicalEntry, "utf8"),
+ };
+ return new NodeFilesystemWorkspaceSession(root, entry);
}
- async load(path: string): Promise<AuthorSourceUnit> {
+ async #loadSource(path: string): Promise<AuthorSourceUnit> {
const canonical = await realpath(resolve(path));
if (!isWithin(this.root, canonical)) {
- throw new NodeCompilerError(
+ throw new WorkspaceError(
"SOURCE_OUTSIDE_ROOT",
- `Source ${canonical} is outside compiler root ${this.root}`,
+ `Source ${canonical} is outside workspace root ${this.root}`,
canonical,
);
}
- const cached = this.#cache.get(canonical);
+ const cached = this.#sourceCache.get(canonical);
if (cached !== undefined) return cached;
const unit: AuthorSourceUnit = {
id: canonical,
name: relative(this.root, canonical) || canonical.split("/").at(-1) || canonical,
text: await readFile(canonical, "utf8"),
};
- this.#cache.set(canonical, unit);
+ this.#sourceCache.set(canonical, unit);
return unit;
}
- readonly resolveSource: AuthorSourceResolver = async (
+ readonly resolveSource = async (
importer: AuthorSourceUnit,
request: AuthorSourceImport,
): Promise<AuthorSourceUnit> => {
if (!request.from.startsWith("./") && !request.from.startsWith("../")) {
- throw new NodeCompilerError(
+ throw new WorkspaceError(
"UNSUPPORTED_SOURCE_IMPORT",
`Source import ${request.from} must be relative; package imports are module imports`,
request.from,
);
}
if (!isWithin(this.root, importer.id)) {
- throw new NodeCompilerError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Source Host`, importer.id);
+ throw new WorkspaceError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Workspace`, importer.id);
}
const edge = `${importer.id}\u0000${request.from}`;
- const locked = this.#edges.get(edge);
+ const locked = this.#sourceEdges.get(edge);
if (locked !== undefined) return locked;
- const loaded = await this.load(resolve(dirname(importer.id), request.from));
- this.#edges.set(edge, loaded);
+ const loaded = await this.#loadSource(resolve(dirname(importer.id), request.from));
+ this.#sourceEdges.set(edge, loaded);
return loaded;
};
- readonly resolveAsset: AuthorSourceAssetResolver = async (
+ readonly resolveAsset = async (
importer: AuthorSourceUnit,
request: AuthorSourceAssetRequest,
) => {
if (!request.from.startsWith("./") && !request.from.startsWith("../")) {
- throw new NodeCompilerError(
+ throw new WorkspaceError(
"UNSUPPORTED_SOURCE_ASSET",
`Source asset ${request.from} must be relative`,
request.from,
);
}
if (!isWithin(this.root, importer.id)) {
- throw new NodeCompilerError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Source Host`, importer.id);
+ throw new WorkspaceError("UNKNOWN_SOURCE_IMPORTER", `${importer.id} is outside this Workspace`, importer.id);
}
const edge = `${importer.id}\u0000${request.from}`;
let canonical = this.#assetEdges.get(edge);
if (canonical === undefined) {
canonical = await realpath(resolve(dirname(importer.id), request.from));
if (!isWithin(this.root, canonical)) {
- throw new NodeCompilerError(
+ throw new WorkspaceError(
"SOURCE_ASSET_OUTSIDE_ROOT",
- `Source asset ${canonical} is outside compiler root ${this.root}`,
+ `Source asset ${canonical} is outside workspace root ${this.root}`,
canonical,
);
}
@@ -122,8 +140,7 @@ export class NodeSourceHost {
return { artifact: { ...artifact } };
};
- /** Exact bytes requested during this compilation, detached from Host caches. */
- sourceArtifacts(): readonly NodeSourceArtifact[] {
+ attachments(): readonly ArtifactAttachment[] {
return [...this.#attachments.values()]
.sort((left, right) => {
const byDigest = left.artifact.digest.localeCompare(right.artifact.digest);
@@ -133,7 +150,21 @@ export class NodeSourceHost {
}
}
-export type NodeSourceArtifact = {
- readonly artifact: BlobRef;
- readonly bytes: Uint8Array;
+export type NodeFilesystemWorkspaceOptions = {
+ /** Fixed containment root. Defaults to the entry SourceUnit directory for each session. */
+ readonly root?: string;
};
+
+/** Node filesystem implementation of the host-neutral, one-compilation Workspace contract. */
+export class NodeFilesystemWorkspace implements Workspace {
+ readonly #root: string | undefined;
+
+ constructor(options: NodeFilesystemWorkspaceOptions = {}) {
+ this.#root = options.root;
+ }
+
+ async open(entryLocator: string): Promise<WorkspaceSession> {
+ const entry = resolve(entryLocator);
+ return await NodeFilesystemWorkspaceSession.open(this.#root ?? dirname(entry), entry);
+ }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ccfb2487..7be0f854 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -98,12 +98,18 @@ importers:
'@svml/elaborator':
specifier: workspace:*
version: link:../elaborator
+ '@svml/host':
+ specifier: workspace:*
+ version: link:../host
'@svml/protocol':
specifier: workspace:*
version: link:../protocol
'@svml/validation':
specifier: workspace:*
version: link:../validation
+ '@svml/workspace-fs-node':
+ specifier: workspace:*
+ version: link:../workspace-fs-node
devDependencies:
'@svml/text':
specifier: workspace:*
@@ -285,6 +291,15 @@ importers:
specifier: workspace:*
version: link:../protocol
+ packages/host:
+ dependencies:
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+
packages/hyperframes:
dependencies:
'@svml/component-kit':
@@ -348,6 +363,9 @@ importers:
'@svml/driver-node':
specifier: workspace:*
version: link:../driver-node
+ '@svml/host':
+ specifier: workspace:*
+ version: link:../host
'@svml/package-loader-node':
specifier: workspace:*
version: link:../package-loader-node
@@ -443,6 +461,9 @@ importers:
'@svml/elaborator':
specifier: workspace:*
version: link:../elaborator
+ '@svml/host':
+ specifier: workspace:*
+ version: link:../host
'@svml/protocol':
specifier: workspace:*
version: link:../protocol
@@ -896,6 +917,18 @@ importers:
specifier: workspace:*
version: link:../protocol
+ packages/workspace-fs-node:
+ dependencies:
+ '@svml/elaborator':
+ specifier: workspace:*
+ version: link:../elaborator
+ '@svml/host':
+ specifier: workspace:*
+ version: link:../host
+ '@svml/protocol':
+ specifier: workspace:*
+ version: link:../protocol
+
packages:
'@aws-sdk/[email protected]':
diff --git a/tsconfig.v2.json b/tsconfig.v2.json
index f98ff784..69d0fce9 100644
--- a/tsconfig.v2.json
+++ b/tsconfig.v2.json
@@ -52,7 +52,9 @@
"@svml/package-loader-node": ["packages/package-loader-node/src/index.ts"],
"@svml/prelude-video": ["packages/prelude-video/src/index.ts"],
"@svml/cli": ["packages/cli/src/index.ts"],
- "@svml/validation": ["packages/validation/src/index.ts"]
+ "@svml/validation": ["packages/validation/src/index.ts"],
+ "@svml/host": ["packages/host/src/index.ts"],
+ "@svml/workspace-fs-node": ["packages/workspace-fs-node/src/index.ts"]
}
},
"include": ["packages/**/*.ts"],