@chrona-city/ugc-kit 1.5.9 → 1.5.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/README.md +95 -5
  2. package/contracts/ugc/public-runtime/v1/README.md +82 -5
  3. package/contracts/ugc/public-runtime/v1/archive.mjs +4 -3
  4. package/contracts/ugc/public-runtime/v1/manifest.mjs +56 -14
  5. package/contracts/ugc/public-runtime/v1/runtime-manifest.schema.json +186 -39
  6. package/contracts/ugc/public-runtime/v1/static-room-runtime.test.mjs +225 -0
  7. package/contracts/ugc/public-runtime/v1/target-compatibility.test.mjs +98 -0
  8. package/docs/harness-onboarding.md +55 -12
  9. package/docs/npm-creator.md +95 -12
  10. package/docs/runtime-download.md +87 -2
  11. package/lib/creator-cli.mjs +6 -4
  12. package/lib/creator-platform.mjs +2 -1
  13. package/lib/creator-toolchain-compat.mjs +9 -0
  14. package/lib/host-ipc/distribution-static-room-semantic-contract/contracts/ugc/public-runtime/v1/manifest.mjs +209 -0
  15. package/lib/host-ipc/distribution-static-room-semantic-contract/contracts/ugc/public-runtime/v1/runtime-manifest.schema.json +898 -0
  16. package/lib/host-ipc/distribution-static-room-semantic-contract/contracts/ugc/registry/v1/conformance/js/capability-resolver.mjs +191 -0
  17. package/lib/host-ipc/host-ipc.schema.json +18 -27
  18. package/lib/host-ipc/runtime-contract.mjs +7 -3
  19. package/lib/host-ipc/source-lock.json +16 -4
  20. package/lib/local-development.mjs +5 -2
  21. package/lib/runtime-host-client.mjs +11 -4
  22. package/lib/runtime-host.mjs +12 -3
  23. package/lib/runtime-install.mjs +12 -3
  24. package/node_modules/@esbuild/darwin-x64/README.md +3 -0
  25. package/node_modules/@esbuild/darwin-x64/bin/esbuild +0 -0
  26. package/node_modules/@esbuild/darwin-x64/package.json +20 -0
  27. package/node_modules/@esbuild/linux-x64/README.md +3 -0
  28. package/node_modules/@esbuild/linux-x64/bin/esbuild +0 -0
  29. package/node_modules/@esbuild/linux-x64/package.json +20 -0
  30. package/package.json +1 -1
  31. package/public-runtime.snapshot.lock.json +13 -5
  32. package/runtime-catalog.json +16 -16
  33. /package/lib/host-ipc/{distribution-document-tool-package-contract → distribution-static-room-semantic-contract}/contracts/ugc/creator-source/v1/tool-package.schema.json +0 -0
@@ -48,6 +48,91 @@ finalization or bypass the final version/source/archive checks. Release tooling,
48
48
  portable integrity, target installation and ordinary gameplay remain separate
49
49
  verification stages; an engineering source/package fixture is not an issued Kit.
50
50
 
51
+ ## Release-only WorldScene and Document catalog composition
52
+
53
+ The catalog prepare CLI accepts its original `producerFile`,
54
+ `clientsDeliveryFile`, `runtimeOrigin` and `outputDirectory` input. A Document
55
+ release may also supply `legacy: {producerFile, clientsDeliveryFile}` for the
56
+ existing WorldScene1.0 content family. Each pair goes through the original
57
+ Producer/delivery/manifest/target checks before the catalog is combined. Both
58
+ must bind the same release source, version, environment and complete toolchain;
59
+ the additional delivery is a normal Producer delivery, not a borrowed Document
60
+ companion or payload-reuse proof. No snapshot or content identity is converted.
61
+ The shared release binding describes the two internal Kit packages, not a
62
+ requirement for historical projects to adopt a new identity. Every historical
63
+ content tuple still needs genuine compatibility and execution evidence; a new
64
+ reference built by the current Kit cannot stand in for that historical input.
65
+
66
+ The release package and the content under test have separate identities. The
67
+ Producer's package, metadata, evidence, source and toolchain bind the new release
68
+ exactly. A retained content input keeps its original `expected` tuple and pinned
69
+ snapshot; when it differs from the carrier, the constructor reenters the existing
70
+ snapshot Reader rather than changing its tool fields. Each target report's `tool`
71
+ must equal that actual content's `expected.tool`, not the carrier version. The two
72
+ content families may therefore have different tool identities while sharing the
73
+ same release package/toolchain/source. This is not a version-range waiver: the
74
+ Runtime must declare and verify the exact content tuple, and the installed
75
+ package, execution target, original reports and cleanup remain independently
76
+ checked. A successful Producer or catalog check is not proof of historical Host
77
+ execution or of an unobserved project's compatibility.
78
+
79
+ The pairing keeps the Document `producer`, `clients` and `targets` unchanged,
80
+ and pins the WorldScene pair under `legacy: {producer, clients, targets}`.
81
+ Final verification reproduces both catalogs, checks the entire selected catalog,
82
+ and returns `legacyTargets` alongside the original `targets`. Catalog CAS and
83
+ source checks apply to both Producers. Removing either pair, changing its inputs
84
+ or manually adding a catalog entry cannot produce a matching final pairing.
85
+
86
+ Portable export/import transports the additional Producer, package, metadata,
87
+ evidence, content, complete snapshot, optional source lock and both target
88
+ manifests/archives/reports as closed `legacy-*` roles. Original logical JSON and
89
+ pins remain byte-identical, with no original-host fallback. The Document
90
+ companion proof and its existing roles are not extended to certify WorldScene.
91
+ This tooling support alone does not supply a playable static Room Runtime: its
92
+ trusted source contract, installed inspection, IPC, actual execution and public
93
+ immutable download must be verified separately before a release is recommended.
94
+
95
+ ## Local selection failures
96
+
97
+ `dev` and `test` read the trusted catalog bundled with the CLI actually invoked,
98
+ including the executable saved in an existing MCP registration. Installing a new
99
+ package does not switch an already running MCP connection. The state directory is
100
+ a verified download/installation cache, not a search path for arbitrary runtimes.
101
+
102
+ The issued city 1.5.9 catalog declares **Node 22.16.0 exactly** for its Linux arm64
103
+ and macOS arm64 runtimes. It does not supply a Linux x64 runtime. In WSL, the
104
+ Linux process architecture is the target, not the Windows host. Node 24.1.0 is
105
+ outside these declared targets; changing only Node still cannot supply a missing
106
+ x64 runtime. These are facts about this issued catalog, not a new compatibility
107
+ rule or a promise about future releases. The pinned manifest `targets` remain
108
+ authoritative.
109
+
110
+ For a no-rebuild local path, use an already available supported arm64 environment,
111
+ its existing verified Kit installation and its Node 22.16.0 executable to run the
112
+ same snapshot through `test`. Call that Node executable and Kit binary explicitly:
113
+ a saved wrapper or MCP entry may still invoke a different Node even after a shell
114
+ version switch. No source reupload or identity/hash change is required. Passing
115
+ the target check still leaves the snapshot's full content tuple to be checked;
116
+ without that tuple, content compatibility remains unknown. This is not a command
117
+ to install Node, alter a user's registration or switch their environment.
118
+
119
+ - `RUNTIME_TARGET_UNSUPPORTED`: no catalog runtime supports the current OS,
120
+ architecture and Node version. Check `node --version` and the pinned manifest
121
+ targets. CLI installation support is not a promise that every Runtime supports
122
+ every newer Node version.
123
+ - `RUNTIME_CONTENT_INCOMPATIBLE`: a target is supported, but no declared row
124
+ matches the snapshot's builder, tool and contracts. Check the selected CLI and
125
+ actual snapshot; do not rewrite its identity, force a runtime ID or reupload to
126
+ bypass the refusal. A version difference alone does not establish semantic
127
+ incompatibility or authorize adding a compatibility row.
128
+
129
+ Both are local selection failures before creator execution, not cloud candidate
130
+ check results. An unknown error, unavailable/corrupt manifest or cancellation
131
+ retains its original failure; no automatic retry or alternate source is selected.
132
+ Existing platform/session Origins are independent of Runtime transport. Preserve
133
+ old registrations and unresolved requests; `--replace-from` below is not an
134
+ automatic cross-Origin migration or permission to edit a saved session.
135
+
51
136
  ## Explicit local distribution (same pinned runtime bytes)
52
137
 
53
138
  Runtime distribution and the creator API are separate. `--platform` never chooses a CDN.
@@ -103,7 +188,7 @@ The caller supplies a canonical, private cache directory outside creator project
103
188
 
104
189
  ## Verified installation
105
190
 
106
- `@chrona/ugc-kit/runtime-install` exports `installPinnedRuntime`, `inspectInstalledRuntime` and `verifyPublicRuntimeSnapshot`. The authoritative distribution contract is mirrored verbatim from Services in `contracts/ugc/public-runtime/v1`, bound by `public-runtime.snapshot.lock.json`; no second archive schema is maintained here. This separate installer snapshot does not change the content compiler's snapshot identity.
191
+ The selected installed package's `/runtime-install` export provides `installPinnedRuntime`, `inspectInstalledRuntime` and `verifyPublicRuntimeSnapshot`. Read its package name from actual installed `package.json`; do not hardcode a legacy scope or change a historical project's identity. The authoritative distribution contract is mirrored verbatim from Services in `contracts/ugc/public-runtime/v1`, bound by `public-runtime.snapshot.lock.json`; no second archive schema is maintained here. This separate installer snapshot does not change the content compiler's snapshot identity.
107
192
 
108
193
  Trusted platform code calls `installPinnedRuntime({cacheDirectory, installationsDirectory, lock, trustedLock, expected, offline?, signal?})`. `lock` is the project selection; `trustedLock` must come from an independently platform-managed catalog, never the same creator-controlled input used as both arguments. Exact supported targets and content toolchains come from the fixed release catalog and verified runtime manifests, not historical examples in this guide. An engineering candidate may still await its matching runtime catalog and is not thereby playable. Older installed archives retain their original catalogs; a matching version label alone is insufficient. The export is an installation primitive for the platform CLI, not a creator permission to add code URLs. Source entitlement, backend runtime installation and formal approval are separate.
109
194
 
@@ -153,7 +238,7 @@ their separate formal consumers.
153
238
 
154
239
  ## Installed host management
155
240
 
156
- `@chrona/ugc-kit/runtime-host` exports `openInstalledRuntimeHost({installationDirectory,lock,trustedLock,content,signal?,onStatus?})`. This platform-facing operation **executes the selected trusted native host**, unlike installation. Never pass a creator-controlled catalog or executable as its trusted selection. Only the exact catalog release and its supported content identities may execute. The Clients-owned IPC validator and Schema are mirrored without changes under `lib/host-ipc`, with their source commit and hashes; the distribution contract above remains the only manifest/archive authority.
241
+ The same installed package's `/runtime-host` export provides `openInstalledRuntimeHost({installationDirectory,lock,trustedLock,content,signal?,onStatus?})`. This platform-facing operation **executes the selected trusted native host**, unlike installation. Never pass a creator-controlled catalog or executable as its trusted selection. Only the exact catalog release and its supported content identities may execute. The Clients-owned IPC validator and Schema are mirrored without changes under `lib/host-ipc`, with their source commit and hashes; the distribution contract above remains the only manifest/archive authority.
157
242
 
158
243
  `content` contains the canonical absolute `snapshotRoot`, raw `snapshotManifestSha256` and complete original `expected` LocalContentSnapshot identity. The original snapshot's builder/tool version is not replaced by the calling CLI version. Before spawning, management rechecks the entire installed release, actual platform, content compatibility and request shape. The child must still verify all snapshot files, policies and sandbox eligibility; an IPC-valid request is not a content approval.
159
244
 
@@ -109,7 +109,7 @@ const messages = {
109
109
  UPGRADE_BUSY: 'Another upgrade or recovery is active. Do not remove its transaction.',
110
110
  UPGRADE_RECOVERY_REQUIRED: 'An unfinished upgrade exists. Stop editing, inspect its owner and use explicit recovery after the owner exits.',
111
111
  UPGRADE_RECOVERY_CONFLICT: 'Recovery conflicts with the committed source or current files. Preserve the transaction for operator inspection.',
112
- CREATOR_SESSION_ORIGIN_MISMATCH: 'The saved session does not match the platform fixed during initialization.',
112
+ CREATOR_SESSION_ORIGIN_MISMATCH: 'The saved session belongs to another platform. Preserve it and inspect auth-status for its Origin. Authorize the intended platform explicitly before further writes; installing or upgrading a Kit does not migrate authorization.',
113
113
  CREATOR_SESSION_SCOPE_REQUIRED: 'Uploading requires source:read, submissions:write and projects:read for live platform preflight. Preserve this session and explicitly start a new authorization in a separate private session directory with these scopes for the selected project; approve it in the browser and exchange it before retrying. No permission was added or revoked.',
114
114
  CREATOR_SESSION_PROJECT_MISMATCH: 'This authorization is restricted to another project. Select its authorized project or explicitly create a new authorization for the intended project; do not edit the saved scope or project binding.',
115
115
  CREATOR_SESSION_RENEWAL_REQUIRED: 'The existing authorization is expired, revoked or uncertain. Preserve it and explicitly configure a new authorization session.',
@@ -132,7 +132,7 @@ const messages = {
132
132
  INSTALL_RELEASE_CHANGED: 'The official current release and immutable metadata differ. No connection was written; retry after the release is consistent.',
133
133
  INVALID_HARNESS_CONFIG: 'The selected Harness configuration is not a supported regular file.',
134
134
  HARNESS_CONFIG_BUSY: 'Another initialization owns this configuration. Retry after it finishes.',
135
- HARNESS_CONFIG_CONFLICT: 'The existing Chrona or unsupported configuration must be resolved explicitly; it was preserved.',
135
+ HARNESS_CONFIG_CONFLICT: 'The existing AI registration was preserved. Inspect its executable, workspace, platform and session. Use --replace-from only for the same binding; a different platform requires an explicit registration and its own authorization, not an edited session.',
136
136
  HARNESS_CONFIG_CHANGED: 'The configuration changed during initialization. Inspect it before retrying.',
137
137
  RUNTIME_NOT_AVAILABLE: 'Isolated tests and dev require a compatible public runtime. No creator code was executed.',
138
138
  INVALID_RUNTIME_SOURCE: 'Use the packaged catalog or an explicitly selected literal loopback runtime origin with --runtime-source local --runtime-origin ORIGIN --allow-local-http true. Upload origins and project catalogs cannot supply runtime trust.',
@@ -185,6 +185,8 @@ for (const code of ['INVALID_INSTALL_RELEASE', 'INSTALL_DOWNLOAD_FAILED', 'INSTA
185
185
  'INSTALL_INVENTORY_INVALID', 'INSTALL_PLATFORM_UNSUPPORTED', 'INSTALL_NODE_UNSUPPORTED', 'INSTALL_PREREQUISITE_MISSING',
186
186
  'INSTALL_CALLER_MISMATCH', 'INSTALL_BUSY', 'INSTALL_CONFLICT', 'INSTALL_NPM_FAILED']) messages[code] = code;
187
187
  Object.assign(messages, {
188
+ RUNTIME_TARGET_UNSUPPORTED: 'The selected runtime or catalog does not support this OS, architecture and Node version. Check node --version and the selected Kit runtime targets. Preserve the project and runtime pins; do not rewrite versions. This local refusal does not describe cloud candidate checks.',
189
+ RUNTIME_CONTENT_INCOMPATIBLE: 'No selected runtime declares a matching builder, tool and contracts row for this snapshot. Check the selected CLI, snapshot and trusted runtime catalog. Preserve the source identity; do not rewrite hashes or reupload to bypass this local refusal. Cloud candidate checks are separate.',
188
190
  INVALID_RESOURCE: 'A resource declaration is missing, malformed or no longer bound to verified content. Review the indicated provenance entry before submitting; explicit author or third-party terms are not rewritten.',
189
191
  SOURCE_PROVENANCE_UPDATED: 'Testing creator declarations were updated from verified asset bytes before source freeze. Review and commit the intended content changes with your normal Git harness, then retry submit. Nothing was uploaded; no extra source questionnaire is required.',
190
192
  SOURCE_PROVENANCE_CONTROLLED_UNKNOWN: 'This imported project lacks explicit controlled scene provenance. Restore its original source-package declarations with the supported preparation path; do not relabel controlled assets as AI-generated.',
@@ -198,8 +200,8 @@ Object.assign(messages, {
198
200
  INSTALL_BUSY: 'Another initialization owns this exact installation. Wait for that process; do not delete its lock.',
199
201
  INSTALL_NPM_FAILED: 'Dependency installation failed. Check access to the public npm registry and retry the official entry; no partial program was registered.',
200
202
  INSTALL_CALLER_MISMATCH: 'The initializer and selected release package/version do not match. Preserve the installed tool and verify the explicit platform and matching release metadata. Do not downgrade to an older webpage recommendation, rename the package or rewrite hashes.',
201
- INSTALL_PLATFORM_UNSUPPORTED: 'This release has no verified installation for this system. Check the supported platforms on the official page.',
202
- INSTALL_NODE_UNSUPPORTED: 'Use a supported Node.js version of at least 22.16.0. The initializer does not upgrade your system tools.',
203
+ INSTALL_PLATFORM_UNSUPPORTED: 'This release metadata has no verified installation for this OS and architecture. Bundled native tools alone do not prove installation or Runtime support. Preserve the project; obtain a release verified for this target, without editing its metadata.',
204
+ INSTALL_NODE_UNSUPPORTED: 'The initializer requires Node.js 22.16.0 or newer; this is not a requirement to match its build Node patch. Runtime execution has its own declared support. The initializer does not change your Node installation.',
203
205
  INSTALL_PREREQUISITE_MISSING: 'Install the documented Node.js/npm and Git prerequisites, then retry. The initializer does not install system tools.',
204
206
  SOURCE_UPDATE_BASE_UNAVAILABLE: 'No verified old base is available for this project or candidate. Preserve the original project and pending key; update cannot safely infer the old main.',
205
207
  SOURCE_UPDATE_CONFLICT: 'The same files changed locally and on the new main. Review the listed paths in your original project; no file or candidate was overwritten.',
@@ -1,4 +1,5 @@
1
1
  import { parseReleaseVersion } from './release-version.mjs';
2
+ import { isCreatorPackageName } from './creator-package-identity.mjs';
2
3
 
3
4
  const fail = code => { throw Object.assign(new Error(code), { code }); };
4
5
  const exact = (v, keys) => v && typeof v === 'object' && !Array.isArray(v)
@@ -50,7 +51,7 @@ export function readPlatformPreflight(data, projectId, now = Date.now()) {
50
51
  || hashes.some(k => !hash(data[k])) || typeof data.policyId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(data.policyId)
51
52
  || !positive(data.validUntilMs) || !positive(data.observedAtMs)) fail('INVALID_CREATOR_RESPONSE');
52
53
  const t = data.toolchain;
53
- if (!exact(t, ['package', 'schemaVersion', 'version', 'snapshotHash', 'sdk']) || t.package !== '@chrona/ugc-kit'
54
+ if (!exact(t, ['package', 'schemaVersion', 'version', 'snapshotHash', 'sdk']) || !isCreatorPackageName(t.package)
54
55
  || t.schemaVersion !== '1.0.0' || !parseReleaseVersion(t.version) || !hash(t.snapshotHash)
55
56
  || !exact(t.sdk, ['client', 'shared']) || t.sdk.client !== '#chrona/client' || t.sdk.shared !== '#chrona/shared') fail('INVALID_CREATOR_RESPONSE');
56
57
  if (!Array.isArray(data.capabilities) || data.capabilities.length > 128) fail('INVALID_CREATOR_RESPONSE');
@@ -59,6 +59,15 @@ export const registeredUpgradeSources = [{ schemaVersion: '1.0.0', package: '@ch
59
59
  sdk: { shared: '#chrona/shared', client: '#chrona/client' } },
60
60
  { schemaVersion: '1.0.0', package: '@chrona/ugc-kit', version: '1.5.8',
61
61
  snapshotHash: 'sha256:2a150f290a642e1c72c9ac887cf787a916e4a1ee6f5e25b47f1d87467198285f',
62
+ sdk: { shared: '#chrona/shared', client: '#chrona/client' } },
63
+ { schemaVersion: '1.0.0', package: '@chrona-city/ugc-kit', version: '1.5.9',
64
+ snapshotHash: 'sha256:1bc56acdc3fdac6999115526f804068c101dcc73ef5054eb2c2c3dc29e381af8',
65
+ sdk: { shared: '#chrona/shared', client: '#chrona/client' } },
66
+ { schemaVersion: '1.0.0', package: '@chrona-city/ugc-kit', version: '1.5.10',
67
+ snapshotHash: 'sha256:1bc56acdc3fdac6999115526f804068c101dcc73ef5054eb2c2c3dc29e381af8',
68
+ sdk: { shared: '#chrona/shared', client: '#chrona/client' } },
69
+ { schemaVersion: '1.0.0', package: '@chrona-city/ugc-kit', version: '1.5.11',
70
+ snapshotHash: 'sha256:1bc56acdc3fdac6999115526f804068c101dcc73ef5054eb2c2c3dc29e381af8',
62
71
  sdk: { shared: '#chrona/shared', client: '#chrona/client' } }];
63
72
 
64
73
  const fail = code => { throw Object.assign(new Error(code), { code }); };
@@ -0,0 +1,209 @@
1
+ import toolPackageSchema from '../../creator-source/v1/tool-package.schema.json' with { type: 'json' };
2
+ import { createHash } from 'node:crypto';
3
+ import { canonicalJson } from '../../registry/v1/conformance/js/capability-resolver.mjs';
4
+
5
+ export const runtimeHash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
6
+ export const runtimeCanonical = canonicalJson;
7
+ export const RUNTIME_LIMITS = Object.freeze({ files: 4096, fileBytes: 33554432, totalBytes: 134217728, archiveBytes: 268435456, manifestBytes: 2097152 });
8
+ const fail = code => { throw Object.assign(new Error(code), { code }); };
9
+ const exact = (v, keys) => v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).sort().join(',') === [...keys].sort().join(',');
10
+ const digest = v => typeof v === 'string' && /^sha256:[a-f0-9]{64}$/.test(v);
11
+ const commit = v => typeof v === 'string' && /^[a-f0-9]{40}$/.test(v);
12
+ const version = v => typeof v === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(v);
13
+ const toolVersion = v => typeof v === 'string' && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-alpha\.[1-9][0-9]*(?:\.[1-9][0-9]*)?)?$(?![\s\S])/.test(v);
14
+ const bounded = (v, min, max) => Number.isSafeInteger(v) && v >= min && v <= max;
15
+ const roles = ['node', 'browser', 'sandbox', 'wasm', 'data', 'license'];
16
+
17
+ export function validRuntimePath(v, { document = false, staticRoom = false } = {}) {
18
+ const roomImplementation = typeof v === 'string' && (document
19
+ ? /^node\/content-room-document-authority\/services\/game-worker\/src\/runtime\/content\/[A-Za-z0-9_-][A-Za-z0-9_.-]*\.js$/.test(v)
20
+ : staticRoom && /^node\/content-room-authority\/services\/game-worker\/src\/runtime\/content\/[A-Za-z0-9_-][A-Za-z0-9_.-]*\.js$/.test(v));
21
+ const localExecutionImplementation = document && typeof v === 'string'
22
+ && /^node\/document-local-execution\/services\/ugc-pipeline\/src\/(?:document-local-execution|private-state-model|private-event-model|private-ecs-model|registry-release)\.mjs$/.test(v);
23
+ return typeof v === 'string' && v.length <= 512 && /^[A-Za-z0-9_@-][A-Za-z0-9_@.-]*(?:\/[A-Za-z0-9_@-][A-Za-z0-9_@.-]*)*$/.test(v)
24
+ && !v.split('/').some(p => ['credentials', 'secrets', 'private'].includes(p.toLowerCase())
25
+ || p.toLowerCase() === 'ugc-pipeline' && !localExecutionImplementation
26
+ || p.toLowerCase() === 'content' && !roomImplementation)
27
+ && !v.split('/').some(p => p.endsWith('.') || /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\.|$)/i.test(p))
28
+ && !/\.(?:pem|key|p12|pfx|glb|gltf)$/i.test(v) && !['runtime.zip', 'runtime-manifest.json'].includes(v.toLowerCase());
29
+ }
30
+
31
+ export function validateRuntimeFiles(files, { document = false, staticRoom = false } = {}) {
32
+ if (!Array.isArray(files) || !files.length || files.length > RUNTIME_LIMITS.files) fail('INVALID_RUNTIME_FILES');
33
+ let previous = '', total = 0;
34
+ const folded = new Set(), directories = new Set();
35
+ for (const f of files) {
36
+ if (!exact(f, ['path', 'bytes', 'sha256', 'role']) || !validRuntimePath(f.path, { document, staticRoom }) || f.path <= previous
37
+ || !digest(f.sha256) || !bounded(f.bytes, 0, RUNTIME_LIMITS.fileBytes) || !roles.includes(f.role)) fail('INVALID_RUNTIME_FILES');
38
+ const parts = f.path.toLowerCase().split('/');
39
+ if (folded.has(parts.join('/')) || directories.has(parts.join('/')) || parts.some((_, i) => folded.has(parts.slice(0, i).join('/')))) fail('INVALID_RUNTIME_FILES');
40
+ for (let i = 1; i < parts.length; i++) directories.add(parts.slice(0, i).join('/'));
41
+ folded.add(parts.join('/')); previous = f.path; total += f.bytes;
42
+ }
43
+ if (total > RUNTIME_LIMITS.totalBytes) fail('RUNTIME_PACKAGE_BUDGET_EXCEEDED');
44
+ return total;
45
+ }
46
+
47
+ export function computeRuntimeHash(value) {
48
+ const { runtimeId, runtimeHash: ignoredHash, archive, ...body } = value;
49
+ return runtimeHash(`chrona.public-runtime.v1\n${canonicalJson(body)}`);
50
+ }
51
+ export const runtimeIdentity = value => `runtime_${computeRuntimeHash(value).slice(7)}`;
52
+ export const runtimeHashFromId = value => {
53
+ if (typeof value !== 'string' || !/^runtime_[a-f0-9]{64}$/.test(value)) fail('INVALID_RUNTIME_MANIFEST');
54
+ return `sha256:${value.slice(8)}`;
55
+ };
56
+ // Actual execution observations are exact versions. A support declaration is a
57
+ // separate, versioned manifest value; neither package engines nor a report
58
+ // silently widens it. Old string targets keep their original exact semantics.
59
+ const nodeVersion = v => {
60
+ if (typeof v !== 'string' || v.length > 48 || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$(?![\s\S])/.test(v)) return null;
61
+ const parts = v.split('.').map(Number);
62
+ return parts.every(Number.isSafeInteger) && parts[0] > 0 ? parts : null;
63
+ };
64
+ const targetPlatform = v => ['darwin', 'linux'].includes(v.os) && ['arm64', 'x64'].includes(v.arch);
65
+ export const validateRuntimeTarget = v => Boolean(exact(v, ['os', 'arch', 'nodeVersion']) && targetPlatform(v) && nodeVersion(v.nodeVersion));
66
+ const validTarget = v => {
67
+ if (exact(v, ['os', 'arch', 'nodeVersion'])) return validateRuntimeTarget(v) && v.nodeVersion === '22.16.0';
68
+ if (!exact(v, ['os', 'arch', 'nodeSupport']) || !targetPlatform(v)
69
+ || !exact(v.nodeSupport, ['schemaVersion', 'lines']) || v.nodeSupport.schemaVersion !== '1.0.0'
70
+ || !Array.isArray(v.nodeSupport.lines) || !v.nodeSupport.lines.length || v.nodeSupport.lines.length > 4) return false;
71
+ return v.nodeSupport.lines.every((line, i, lines) => exact(line, ['major', 'minimum'])
72
+ && Number.isSafeInteger(line.major) && line.major > 0 && nodeVersion(line.minimum)?.[0] === line.major
73
+ && (!i || line.major > lines[i - 1].major));
74
+ };
75
+ const targetMatches = (declared, actual) => {
76
+ if (Object.hasOwn(declared, 'nodeVersion')) return canonicalJson(declared) === canonicalJson(actual);
77
+ const observed = nodeVersion(actual.nodeVersion);
78
+ return declared.os === actual.os && declared.arch === actual.arch && declared.nodeSupport.lines.some(line => {
79
+ if (observed[0] !== line.major) return false;
80
+ const minimum = nodeVersion(line.minimum);
81
+ return observed[1] > minimum[1] || observed[1] === minimum[1] && observed[2] >= minimum[2];
82
+ });
83
+ };
84
+ // The Host IPC and Runtime compatibility use the same exact tuple definition.
85
+ // `document` is selected from the verified snapshot/runtime variant, not a
86
+ // claim made by the child. This validates format, not source approval or access.
87
+ export function validateRuntimeContentContracts(c, { document = false } = {}) {
88
+ return exact(c, ['registryVersion', 'registryHash', 'resolutionPolicyHash', 'contractSetHashes']) && version(c.registryVersion)
89
+ && digest(c.registryHash) && digest(c.resolutionPolicyHash)
90
+ && exact(c.contractSetHashes, document ? ['localContent', 'worldScene', 'documentPresentation'] : ['localContent', 'worldScene'])
91
+ && Object.values(c.contractSetHashes).every(digest);
92
+ }
93
+ function validContentRow(row, document = false) {
94
+ if (!exact(row, ['builderVersion', 'tool', 'contracts']) || row.builderVersion !== (document ? 'local-content@1.1.0' : 'local-content@1.0.0')) return false;
95
+ const t = row.tool, c = row.contracts;
96
+ return exact(t, ['packageName', 'packageVersion', 'kitVersion', 'kitSnapshotHash']) && toolPackageSchema.enum.includes(t.packageName)
97
+ && toolVersion(t.packageVersion) && toolVersion(t.kitVersion) && digest(t.kitSnapshotHash)
98
+ && validateRuntimeContentContracts(c, { document });
99
+ }
100
+
101
+ export function validateRuntimeManifest(v) {
102
+ if (!exact(v, ['schemaVersion', 'kind', 'apiVersion', 'runtimeId', 'runtimeHash', 'executionTier', 'source', 'targets', 'compatibility', 'entrypoints', 'files', 'archive'])
103
+ || !['1.0.0', '1.1.0'].includes(v.schemaVersion) || v.kind !== 'public-local-runtime' || v.apiVersion !== '1.0.0'
104
+ || v.executionTier !== 'public-untrusted' || !/^runtime_[a-f0-9]{64}$/.test(v.runtimeId ?? '') || !digest(v.runtimeHash)) fail('INVALID_RUNTIME_MANIFEST');
105
+ const document = v.schemaVersion === '1.1.0';
106
+ // Static Room is a distinct source closure, not Document or historical Flight.
107
+ // The exact source shape selects only its fixed implementation namespace.
108
+ const staticRoom = !document && exact(v.source, ['clientsCommitSha', 'publicNode', 'contentRoom']);
109
+ const sourceKeys = document ? ['publicNode', 'contentRoom', 'documentAuthority']
110
+ : staticRoom ? ['publicNode', 'contentRoom'] : ['publicNode', 'publicFlight'];
111
+ if (!exact(v.source, ['clientsCommitSha', ...sourceKeys]) || !commit(v.source.clientsCommitSha)) fail('INVALID_RUNTIME_SOURCE');
112
+ validateRuntimeFiles(v.files, { document, staticRoom });
113
+ const files = new Map(v.files.map(f => [f.path, f]));
114
+ const reference = (p, role) => validRuntimePath(p, { document, staticRoom }) && files.get(p)?.role === role;
115
+ for (const key of sourceKeys) {
116
+ const source = v.source[key];
117
+ if (!exact(source, ['commitSha', 'sourceHash', 'lockPath']) || !commit(source.commitSha) || !digest(source.sourceHash)
118
+ || !reference(source.lockPath, 'data')) fail('INVALID_RUNTIME_SOURCE');
119
+ }
120
+ if (new Set(sourceKeys.map(key => v.source[key].lockPath)).size !== sourceKeys.length) fail('INVALID_RUNTIME_SOURCE');
121
+ const c = v.compatibility;
122
+ if (!Array.isArray(v.targets) || !v.targets.length || v.targets.length > 4 || v.targets.some(t => !validTarget(t))
123
+ || v.targets.some((t, i) => i && canonicalJson(t) <= canonicalJson(v.targets[i - 1]))) fail('INVALID_RUNTIME_COMPATIBILITY');
124
+ if (!exact(c, ['protocol', 'content', 'policyFiles', 'localContentContract'])
125
+ || !exact(c.protocol, ['major', 'schemaRevision']) || c.protocol.major !== 1
126
+ || !(c.protocol.schemaRevision === 2 || document && c.protocol.schemaRevision === 3)
127
+ || !Array.isArray(c.content) || !c.content.length || c.content.length > 8
128
+ || !(document ? exact(c.policyFiles, ['documentPresentation']) && reference(c.policyFiles.documentPresentation, 'data')
129
+ : exact(c.policyFiles, ['worldScene', 'sceneRender']) && reference(c.policyFiles.worldScene, 'data')
130
+ && reference(c.policyFiles.sceneRender, 'data') && c.policyFiles.worldScene !== c.policyFiles.sceneRender)
131
+ || !reference(c.localContentContract, 'node')) fail('INVALID_RUNTIME_COMPATIBILITY');
132
+ let previous = '';
133
+ for (const row of c.content) {
134
+ if (!validContentRow(row, document) || canonicalJson(row) <= previous) fail('INVALID_RUNTIME_COMPATIBILITY');
135
+ previous = canonicalJson(row);
136
+ }
137
+ if (!exact(v.entrypoints, ['api', 'browser', 'sandbox'])
138
+ || v.entrypoints.api !== 'node/host.mjs' || !reference(v.entrypoints.api, 'node')
139
+ || v.entrypoints.browser !== 'web/index.html' || !reference(v.entrypoints.browser, 'browser')
140
+ || !reference('web/app.js', 'browser')
141
+ || v.entrypoints.sandbox !== (document ? 'sandbox/document-view.html' : 'sandbox/public-content-bridge.html')
142
+ || !reference(v.entrypoints.sandbox, 'sandbox')
143
+ || !document && !reference('sandbox/public-content-worker.js', 'sandbox')
144
+ || !v.files.some(f => f.role === 'wasm' && f.path.endsWith('.wasm')) || !v.files.some(f => f.role === 'license' && f.path.startsWith('licenses/'))) fail('INVALID_RUNTIME_ENTRYPOINT');
145
+ if (!exact(v.archive, ['path', 'format', 'bytes', 'sha256']) || v.archive.path !== 'runtime.zip' || v.archive.format !== 'zip-store-v1'
146
+ || !bounded(v.archive.bytes, 22, RUNTIME_LIMITS.archiveBytes) || !digest(v.archive.sha256)) fail('INVALID_RUNTIME_ARCHIVE');
147
+ const expectedBytes = 22 + v.files.reduce((n, f) => n + f.bytes + 76 + 2 * Buffer.byteLength(f.path), 0);
148
+ if (v.archive.bytes !== expectedBytes || runtimeIdentity(v) !== v.runtimeId || computeRuntimeHash(v) !== v.runtimeHash) fail('RUNTIME_PACKAGE_IDENTITY_MISMATCH');
149
+ return v;
150
+ }
151
+
152
+ export function verifyRuntimeManifest(bytes, expectedHash) {
153
+ if (!(bytes instanceof Uint8Array) || bytes.byteLength > RUNTIME_LIMITS.manifestBytes || !digest(expectedHash)
154
+ || runtimeHash(bytes) !== expectedHash) fail('RUNTIME_MANIFEST_HASH_MISMATCH');
155
+ let value;
156
+ try { value = JSON.parse(Buffer.from(bytes)); } catch { fail('INVALID_RUNTIME_MANIFEST'); }
157
+ validateRuntimeManifest(value);
158
+ if (!Buffer.from(`${canonicalJson(value)}\n`).equals(Buffer.from(bytes))) fail('INVALID_RUNTIME_MANIFEST');
159
+ return value;
160
+ }
161
+
162
+ function artifactPin(v, maximum, allowLocalHttp) {
163
+ if (!exact(v, ['url', 'bytes', 'sha256']) || !bounded(v.bytes, 1, maximum) || !digest(v.sha256) || typeof v.url !== 'string' || v.url.length > 2048) fail('INVALID_RUNTIME_LOCK');
164
+ let url;
165
+ try { url = new URL(v.url); } catch { fail('INVALID_RUNTIME_LOCK'); }
166
+ if (url.href !== v.url || url.username || url.password || url.search || url.hash
167
+ || !(url.protocol === 'https:' || allowLocalHttp && url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname))) fail('INVALID_RUNTIME_LOCK');
168
+ }
169
+
170
+ function validateLockShape(lock, allowLocalHttp) {
171
+ if (typeof allowLocalHttp !== 'boolean' || !exact(lock, ['schemaVersion', 'kind', 'runtimeId', 'runtimeHash', 'manifest', 'archive'])
172
+ || lock.schemaVersion !== '1.0.0' || lock.kind !== 'public-runtime-lock' || !/^runtime_[a-f0-9]{64}$/.test(lock.runtimeId ?? '')) fail('INVALID_RUNTIME_LOCK');
173
+ if (runtimeHashFromId(lock.runtimeId) !== lock.runtimeHash) fail('INVALID_RUNTIME_LOCK');
174
+ artifactPin(lock.manifest, RUNTIME_LIMITS.manifestBytes, allowLocalHttp); artifactPin(lock.archive, RUNTIME_LIMITS.archiveBytes, allowLocalHttp);
175
+ }
176
+
177
+ export function validateRuntimeLock(lock, trustedLock, { allowLocalHttp = false } = {}) {
178
+ validateLockShape(lock, allowLocalHttp);
179
+ if (!trustedLock || canonicalJson(lock) !== canonicalJson(trustedLock)) fail('UNTRUSTED_RUNTIME_LOCK');
180
+ return lock;
181
+ }
182
+
183
+ export function assertRuntimeTargetCompatibility(manifest, { target = { os: process.platform, arch: process.arch, nodeVersion: process.versions.node } } = {}) {
184
+ validateRuntimeManifest(manifest);
185
+ if (!validateRuntimeTarget(target) || !manifest.targets.some(t => targetMatches(t, target))) fail('RUNTIME_TARGET_UNSUPPORTED');
186
+ return true;
187
+ }
188
+
189
+ export function assertRuntimeCompatibility(manifest, { target, expected } = {}) {
190
+ assertRuntimeTargetCompatibility(manifest, { target });
191
+ const row = { builderVersion: expected?.builderVersion, tool: expected?.tool, contracts: expected?.contracts };
192
+ const staticRoom = manifest.schemaVersion === '1.0.0' && exact(manifest.source, ['clientsCommitSha', 'publicNode', 'contentRoom']);
193
+ // Tool versions retain snapshot/report provenance. Only this validated static
194
+ // Room family matches the actual Builder/contracts/SDK interface instead.
195
+ if (!validContentRow(row, manifest.schemaVersion === '1.1.0') || !manifest.compatibility.content.some(r => staticRoom
196
+ ? r.builderVersion === row.builderVersion && canonicalJson(r.contracts) === canonicalJson(row.contracts)
197
+ && r.tool.packageName === row.tool.packageName && r.tool.kitSnapshotHash === row.tool.kitSnapshotHash
198
+ : canonicalJson(r) === canonicalJson(row))) fail('RUNTIME_CONTENT_INCOMPATIBLE');
199
+ return true;
200
+ }
201
+
202
+ export function verifyRuntimePair(manifest, lock, expected, { target, allowLocalHttp = false } = {}) {
203
+ validateLockShape(lock, allowLocalHttp);
204
+ assertRuntimeCompatibility(manifest, { target, expected });
205
+ const bytes = Buffer.from(`${canonicalJson(manifest)}\n`);
206
+ if (manifest.runtimeId !== lock.runtimeId || manifest.runtimeHash !== lock.runtimeHash || manifest.archive.sha256 !== lock.archive.sha256
207
+ || manifest.archive.bytes !== lock.archive.bytes || bytes.length !== lock.manifest.bytes || runtimeHash(bytes) !== lock.manifest.sha256) fail('RUNTIME_PAIR_MISMATCH');
208
+ return { runtimeId: manifest.runtimeId, runtimeHash: manifest.runtimeHash, manifestSha256: lock.manifest.sha256, apiVersion: manifest.apiVersion, ready: false };
209
+ }