@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
@@ -0,0 +1,225 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { readFile, mkdir, writeFile } from 'node:fs/promises';
4
+ import { resolve, join } from 'node:path';
5
+ import { pathToFileURL } from 'node:url';
6
+ import { createFormatFixture } from './format-fixture.mjs';
7
+ import { encodeRuntimeArchive, decodeRuntimeArchive } from './archive.mjs';
8
+ import { runtimeCanonical, runtimeHash, runtimeIdentity, computeRuntimeHash, validateRuntimeManifest,
9
+ verifyRuntimeManifest, verifyRuntimePair, assertRuntimeCompatibility, validRuntimePath } from './manifest.mjs';
10
+
11
+ const prefix = 'node/content-room-authority/';
12
+ const implementation = `${prefix}services/game-worker/src/runtime/content/content-room-source.js`;
13
+ const sort = entries => entries.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
14
+ function assemble(entries, roomSource) {
15
+ const f = createFormatFixture(), manifest = structuredClone(f.manifest);
16
+ delete manifest.source.publicFlight;
17
+ manifest.source.contentRoom = roomSource;
18
+ entries = sort([...f.entries, ...entries]);
19
+ const archive = encodeRuntimeArchive(entries, { staticRoom: true });
20
+ manifest.files = entries.map(e => ({ path: e.path, role: e.role, bytes: e.bytes.length, sha256: runtimeHash(e.bytes) }));
21
+ manifest.archive = { ...manifest.archive, bytes: archive.length, sha256: runtimeHash(archive) };
22
+ manifest.runtimeHash = computeRuntimeHash(manifest); manifest.runtimeId = runtimeIdentity(manifest);
23
+ const bytes = Buffer.from(`${runtimeCanonical(manifest)}\n`), manifestHash = runtimeHash(bytes);
24
+ const lock = { ...f.lock, runtimeId: manifest.runtimeId, runtimeHash: manifest.runtimeHash,
25
+ manifest: { ...f.lock.manifest, bytes: bytes.length, sha256: manifestHash },
26
+ archive: { ...f.lock.archive, bytes: archive.length, sha256: runtimeHash(archive) } };
27
+ return { manifest, archive, entries, bytes, manifestHash, lock, target: f.target, expected: f.expected };
28
+ }
29
+ function fixture() {
30
+ return assemble([
31
+ { path: implementation, role: 'node', bytes: Buffer.from('STATIC ROOM FORMAT FIXTURE ONLY\n') },
32
+ { path: `${prefix}source-lock.json`, role: 'data', bytes: Buffer.from('SOURCE LOCK FORMAT FIXTURE ONLY\n') }
33
+ ], { commitSha: 'e'.repeat(40), sourceHash: runtimeHash('room-format-fixture'), lockPath: `${prefix}source-lock.json` });
34
+ }
35
+ const rehash = m => { m.runtimeHash = computeRuntimeHash(m); m.runtimeId = runtimeIdentity(m); };
36
+
37
+ test('static Room archive Writer and Reader bind independent Room without Document or Flight claims', () => {
38
+ const f = fixture(), m = verifyRuntimeManifest(f.bytes, f.manifestHash);
39
+ assert.equal(m.schemaVersion, '1.0.0');
40
+ assert.deepEqual(Object.keys(m.source).sort(), ['clientsCommitSha', 'contentRoom', 'publicNode']);
41
+ assert.equal(m.source.documentAuthority, undefined); assert.equal(m.source.publicFlight, undefined);
42
+ assert.deepEqual(decodeRuntimeArchive(f.archive, m), f.entries);
43
+ assert.equal(verifyRuntimePair(m, f.lock, f.expected, { target: f.target }).ready, false);
44
+ const wrong = structuredClone(f.expected); wrong.contracts.contractSetHashes.worldScene = runtimeHash('wrong-content');
45
+ assert.throws(() => assertRuntimeCompatibility(m, { target: f.target, expected: wrong }), { code: 'RUNTIME_CONTENT_INCOMPATIBLE' });
46
+ });
47
+
48
+ test('static Room admits its fixed implementation namespace without opening author or Document paths', () => {
49
+ assert.equal(validRuntimePath(implementation), false);
50
+ assert.equal(validRuntimePath(implementation, { staticRoom: true }), true);
51
+ assert.equal(validRuntimePath(implementation, { document: true }), false);
52
+ for (const path of ['content/shared/main.js', `${prefix}content/main.js`,
53
+ `${prefix}services/game-worker/src/runtime/content/author.glb`,
54
+ `${prefix}services/game-worker/src/runtime/content/private/main.js`,
55
+ `${prefix}services/ugc-pipeline/src/local-content.mjs`,
56
+ 'node/content-room-document-authority/services/game-worker/src/runtime/content/content-room-source.js',
57
+ 'node/other/services/game-worker/src/runtime/content/content-room-source.js'])
58
+ assert.equal(validRuntimePath(path, { staticRoom: true }), false, path);
59
+ assert.throws(() => encodeRuntimeArchive(fixture().entries), { code: 'INVALID_RUNTIME_FILES' });
60
+ });
61
+
62
+ test('static Room source variants, lock references, inventory and archive bytes remain exact', () => {
63
+ for (const [mutate, code] of [
64
+ [m => { m.source.publicFlight = m.source.contentRoom; }, 'INVALID_RUNTIME_SOURCE'],
65
+ [m => { m.source.documentAuthority = m.source.contentRoom; }, 'INVALID_RUNTIME_SOURCE'],
66
+ [m => { delete m.source.contentRoom; }, 'INVALID_RUNTIME_SOURCE'],
67
+ [m => { m.source.contentRoom.lockPath = m.source.publicNode.lockPath; }, 'INVALID_RUNTIME_SOURCE'],
68
+ [m => { m.source.contentRoom.lockPath = 'data/missing.json'; }, 'INVALID_RUNTIME_SOURCE'],
69
+ [m => { m.source.contentRoom.sourceHash = 'unknown'; }, 'INVALID_RUNTIME_SOURCE'],
70
+ [m => { m.schemaVersion = '1.1.0'; }, 'INVALID_RUNTIME_SOURCE'],
71
+ [m => { m.compatibility.protocol.schemaRevision = 3; }, 'INVALID_RUNTIME_COMPATIBILITY'],
72
+ [m => { m.compatibility.content[0].builderVersion = 'local-content@1.1.0'; }, 'INVALID_RUNTIME_COMPATIBILITY']
73
+ ]) {
74
+ const { manifest } = fixture(); mutate(manifest); rehash(manifest);
75
+ assert.throws(() => validateRuntimeManifest(manifest), { code });
76
+ }
77
+ const f = fixture(), wrong = Buffer.from(f.archive); wrong[50] ^= 1;
78
+ assert.throws(() => decodeRuntimeArchive(wrong, f.manifest), { code: 'RUNTIME_ARCHIVE_HASH_MISMATCH' });
79
+ const altered = structuredClone(f.manifest); altered.files.find(x => x.path === implementation).sha256 = runtimeHash('drift');
80
+ assert.throws(() => validateRuntimeManifest(altered), { code: 'RUNTIME_PACKAGE_IDENTITY_MISMATCH' });
81
+ rehash(altered);
82
+ assert.throws(() => decodeRuntimeArchive(f.archive, altered), { code: 'RUNTIME_ARCHIVE_HASH_MISMATCH' });
83
+ });
84
+
85
+ test('schema preserves two exact static source alternatives and the separate Document source', async () => {
86
+ const s = JSON.parse(await readFile(new URL('./runtime-manifest.schema.json', import.meta.url)));
87
+ const variants = s.allOf[0].then.properties.source.oneOf;
88
+ assert.equal(variants.length, 2);
89
+ assert.deepEqual(variants.map(x => x.required.slice().sort()), [
90
+ ['clientsCommitSha', 'publicFlight', 'publicNode'], ['clientsCommitSha', 'contentRoom', 'publicNode']
91
+ ]);
92
+ for (const v of variants) assert.equal(v.additionalProperties, false);
93
+ assert.deepEqual(s.properties.source.oneOf.map(x => x.required.slice().sort()), [
94
+ variants[0].required.slice().sort(), ['clientsCommitSha', 'contentRoom', 'documentAuthority', 'publicNode'],
95
+ variants[1].required.slice().sort()
96
+ ]);
97
+ });
98
+
99
+ test('only static Room compatibility treats valid tool versions as provenance, preserving interface identity', () => {
100
+ const f = fixture();
101
+ for (const field of ['packageVersion', 'kitVersion']) {
102
+ for (const version of ['1.5.9', '1.5.10', '1.5.11']) {
103
+ // Version shape vectors only; 1.5.11 here is not a real Kit reference.
104
+ const expected = structuredClone(f.expected); expected.tool[field] = version;
105
+ assert.equal(verifyRuntimePair(f.manifest, f.lock, expected, { target: f.target }).ready, false);
106
+ assert.equal(f.expected.tool[field], '0.2.5');
107
+ }
108
+ for (const version of [undefined, null, '', '01.5.9', '1.5', '1.5.9-beta.1']) {
109
+ const expected = structuredClone(f.expected); expected.tool[field] = version;
110
+ assert.throws(() => assertRuntimeCompatibility(f.manifest, { target: f.target, expected }), { code: 'RUNTIME_CONTENT_INCOMPATIBLE' });
111
+ }
112
+ }
113
+ for (const mutate of [
114
+ row => { row.builderVersion = 'local-content@1.1.0'; },
115
+ row => { row.tool.packageName = '@chrona-city/ugc-kit'; },
116
+ row => { row.tool.kitSnapshotHash = runtimeHash('another-sdk'); },
117
+ row => { row.tool.extra = true; },
118
+ row => { row.contracts.registryVersion = '1.1.11'; },
119
+ row => { row.contracts.registryHash = runtimeHash('another-registry'); },
120
+ row => { row.contracts.resolutionPolicyHash = runtimeHash('another-policy'); },
121
+ row => { row.contracts.contractSetHashes.localContent = runtimeHash('another-builder'); },
122
+ row => { row.contracts.contractSetHashes.worldScene = runtimeHash('another-world'); }
123
+ ]) {
124
+ const expected = structuredClone(f.expected); mutate(expected);
125
+ assert.throws(() => assertRuntimeCompatibility(f.manifest, { target: f.target, expected }), { code: 'RUNTIME_CONTENT_INCOMPATIBLE' });
126
+ }
127
+ assert.throws(() => assertRuntimeCompatibility(f.manifest, { target: { ...f.target, nodeVersion: '24.1.0' }, expected: f.expected }),
128
+ { code: 'RUNTIME_TARGET_UNSUPPORTED' });
129
+ const malformed = structuredClone(f.manifest); malformed.compatibility.content[0].tool.kitVersion = 'unknown'; rehash(malformed);
130
+ assert.throws(() => assertRuntimeCompatibility(malformed, f), { code: 'INVALID_RUNTIME_COMPATIBILITY' });
131
+ });
132
+
133
+ test('Flight and Document preserve complete version matching and cannot select the static Room rule', () => {
134
+ const legacy = createFormatFixture();
135
+ for (const key of ['packageVersion', 'kitVersion']) {
136
+ const expected = structuredClone(legacy.expected); expected.tool[key] = '1.5.11';
137
+ assert.throws(() => assertRuntimeCompatibility(legacy.manifest, { target: legacy.target, expected }), { code: 'RUNTIME_CONTENT_INCOMPATIBLE' });
138
+ }
139
+ const document = fixture(); delete document.manifest.source.contentRoom;
140
+ document.manifest.source.contentRoom = { commitSha: 'e'.repeat(40), sourceHash: runtimeHash('doc-room'), lockPath: 'data/flight.json' };
141
+ document.manifest.source.documentAuthority = { commitSha: 'f'.repeat(40), sourceHash: runtimeHash('doc-authority'), lockPath: 'data/style.json' };
142
+ document.manifest.schemaVersion = '1.1.0';
143
+ document.manifest.files = document.manifest.files.filter(row => row.path !== implementation);
144
+ document.manifest.files.push({ path: 'sandbox/document-view.html', role: 'sandbox', bytes: 0, sha256: runtimeHash('') });
145
+ document.manifest.files.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
146
+ document.manifest.compatibility.content[0].builderVersion = 'local-content@1.1.0';
147
+ document.manifest.compatibility.content[0].contracts.contractSetHashes.documentPresentation = runtimeHash('doc');
148
+ document.manifest.compatibility.policyFiles = { documentPresentation: 'data/world.json' };
149
+ document.manifest.entrypoints.sandbox = 'sandbox/document-view.html';
150
+ document.manifest.archive.bytes = 22 + document.manifest.files.reduce((n, f) => n + f.bytes + 76 + 2 * Buffer.byteLength(f.path), 0);
151
+ rehash(document.manifest); validateRuntimeManifest(document.manifest);
152
+ for (const key of ['packageVersion', 'kitVersion']) {
153
+ const expected = structuredClone(document.manifest.compatibility.content[0]); expected.tool[key] = '1.5.11';
154
+ assert.throws(() => assertRuntimeCompatibility(document.manifest, { target: document.target, expected }), { code: 'RUNTIME_CONTENT_INCOMPATIBLE' });
155
+ }
156
+ });
157
+
158
+ test('unchanged real 159 and 1510 Builder outputs match one static Room row through the original full Reader', {
159
+ skip: !process.env.CHRONA_STATIC_SEMANTIC_INPUTS || !process.env.CHRONA_STATIC_SEMANTIC_READER
160
+ }, async () => {
161
+ const reader = await import(pathToFileURL(resolve(process.env.CHRONA_STATIC_SEMANTIC_READER)));
162
+ const rows = [], pins = [];
163
+ for (const file of JSON.parse(process.env.CHRONA_STATIC_SEMANTIC_INPUTS)) {
164
+ const original = await readFile(file), content = JSON.parse(original);
165
+ const input = await reader.openLocalContentInput(content, { runtimeReader: true });
166
+ try {
167
+ assert.equal(input.snapshot.schemaVersion, '1.0.0');
168
+ assert.deepEqual(input.validation.identity, content.expected);
169
+ let bytes = 0;
170
+ for (const item of input.snapshot.files) bytes += (await input.files.read(item.path)).length;
171
+ rows.push(structuredClone(input.validation.identity));
172
+ pins.push({ inputHash: runtimeHash(original), expected: input.validation.identity, files: input.snapshot.files.length, bytes });
173
+ } finally { await input.close(); }
174
+ assert.deepEqual(await readFile(file), original);
175
+ }
176
+ assert.equal(rows.length, 2);
177
+ assert.deepEqual(rows.map(row => row.tool.packageVersion), ['1.5.9', '1.5.10']);
178
+ assert.deepEqual(rows[0].contracts, rows[1].contracts);
179
+ assert.equal(rows[0].tool.kitSnapshotHash, rows[1].tool.kitSnapshotHash);
180
+ const f = fixture();
181
+ f.manifest.compatibility.content = [{ builderVersion: rows[1].builderVersion, tool: rows[1].tool, contracts: rows[1].contracts }];
182
+ rehash(f.manifest);
183
+ const manifestBytes = Buffer.from(`${runtimeCanonical(f.manifest)}\n`);
184
+ f.lock.runtimeId = f.manifest.runtimeId; f.lock.runtimeHash = f.manifest.runtimeHash;
185
+ f.lock.manifest = { ...f.lock.manifest, bytes: manifestBytes.length, sha256: runtimeHash(manifestBytes) };
186
+ const manifest = verifyRuntimeManifest(manifestBytes, runtimeHash(manifestBytes));
187
+ for (const expected of rows) assert.equal(verifyRuntimePair(manifest, f.lock, expected, { target: f.target }).ready, false);
188
+ if (process.env.CHRONA_STATIC_SEMANTIC_OUTPUT) await writeFile(process.env.CHRONA_STATIC_SEMANTIC_OUTPUT,
189
+ `${JSON.stringify({ fixtureOnly: true, executable: false, actual1511ReferenceVerified: false,
190
+ inputs: pins, manifestBytesBase64: manifestBytes.toString('base64'), manifestHash: runtimeHash(manifestBytes),
191
+ lock: f.lock, target: f.target, hostVerified: false }, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
192
+ });
193
+
194
+ test('original 70-source Room Reader output survives real archive Writer and independent decode', {
195
+ skip: !process.env.CHRONA_STATIC_ROOM_DIRECTORY || !process.env.CHRONA_STATIC_ROOM_READER
196
+ }, async () => {
197
+ // Only the original fixed Reader can supply this source. The outer host/WASM
198
+ // fixture remains non-executable; no installed Runtime or Guest is claimed.
199
+ const directory = resolve(process.env.CHRONA_STATIC_ROOM_DIRECTORY);
200
+ const reader = await import(pathToFileURL(resolve(process.env.CHRONA_STATIC_ROOM_READER)));
201
+ const { lock, files } = await reader.readContentRoomAuthority(directory);
202
+ assert.equal(lock.manifest.files.length, 70);
203
+ const entries = [...files].map(([path, bytes]) => ({ path: `${prefix}${path}`, bytes,
204
+ role: /\.(?:js|mjs|cjs)$/.test(path) ? 'node' : 'data' }));
205
+ const lockBytes = await readFile(join(directory, 'source-lock.json'));
206
+ entries.push({ path: `${prefix}source-lock.json`, bytes: lockBytes, role: 'data' });
207
+ const f = assemble(entries, { commitSha: lock.sourceCommit, sourceHash: lock.manifest.sourceHash,
208
+ lockPath: `${prefix}source-lock.json` });
209
+ const m = verifyRuntimeManifest(f.bytes, f.manifestHash);
210
+ const decoded = new Map(decodeRuntimeArchive(f.archive, m).map(x => [x.path, x.bytes]));
211
+ for (const row of lock.manifest.files) assert.equal(runtimeHash(decoded.get(`${prefix}${row.path}`)), `sha256:${row.sha256}`);
212
+ assert.deepEqual(decoded.get(`${prefix}source-lock.json`), lockBytes);
213
+ assert.equal(verifyRuntimePair(m, f.lock, f.expected, { target: f.target }).ready, false);
214
+ if (process.env.CHRONA_STATIC_ROOM_OUTPUT) {
215
+ const output = resolve(process.env.CHRONA_STATIC_ROOM_OUTPUT);
216
+ await mkdir(output, { recursive: true, mode: 0o700 });
217
+ for (const [name, bytes] of [['runtime-manifest.json', f.bytes], ['runtime.zip', f.archive],
218
+ ['runtime-lock.json', Buffer.from(`${JSON.stringify(f.lock, null, 2)}\n`)],
219
+ ['result.json', Buffer.from(`${JSON.stringify({ fixtureOnly: true, executable: false,
220
+ originalRoomFiles: lock.manifest.files.length, roomCommit: lock.sourceCommit, roomSourceHash: lock.manifest.sourceHash,
221
+ roomLockHash: runtimeHash(lockBytes), manifestHash: f.manifestHash, archiveHash: runtimeHash(f.archive),
222
+ files: m.files.length, archiveBytes: f.archive.length, ready: false }, null, 2)}\n`)]])
223
+ await writeFile(join(output, name), bytes, { flag: 'wx', mode: 0o600 });
224
+ }
225
+ });
@@ -0,0 +1,98 @@
1
+ import test from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { readFile, writeFile } from 'node:fs/promises';
4
+ import { createFormatFixture } from './format-fixture.mjs';
5
+ import { runtimeCanonical, runtimeHash, runtimeIdentity, computeRuntimeHash, verifyRuntimeManifest,
6
+ validateRuntimeManifest, validateRuntimeTarget, assertRuntimeTargetCompatibility, assertRuntimeCompatibility, verifyRuntimePair } from './manifest.mjs';
7
+ import { decodeRuntimeArchive } from './archive.mjs';
8
+
9
+ const target = (nodeVersion, os = 'linux', arch = 'x64') => ({ os, arch, nodeVersion });
10
+ // Contract vectors only: these declarations do not certify Linux/Node24 execution.
11
+ const support = () => ({ os: 'linux', arch: 'x64', nodeSupport: { schemaVersion: '1.0.0',
12
+ lines: [{ major: 22, minimum: '22.16.0' }, { major: 24, minimum: '24.1.0' }] } });
13
+ function seal(f) {
14
+ f.manifest.runtimeHash = computeRuntimeHash(f.manifest); f.manifest.runtimeId = runtimeIdentity(f.manifest);
15
+ f.bytes = Buffer.from(`${runtimeCanonical(f.manifest)}\n`); f.manifestHash = runtimeHash(f.bytes);
16
+ Object.assign(f.lock, { runtimeId: f.manifest.runtimeId, runtimeHash: f.manifest.runtimeHash });
17
+ Object.assign(f.lock.manifest, { bytes: f.bytes.length, sha256: f.manifestHash });
18
+ return f;
19
+ }
20
+ const declared = () => { const f = createFormatFixture(); f.manifest.targets = [support()]; return seal(f); };
21
+
22
+ test('target-only API preserves old exact targets and the unchanged golden identity', async () => {
23
+ const f = createFormatFixture(), golden = JSON.parse(await readFile(new URL('./golden.json', import.meta.url)));
24
+ assert.equal(f.manifestHash, golden.manifestSha256);
25
+ assert.equal(assertRuntimeTargetCompatibility(f.manifest, { target: f.target }), true);
26
+ for (const next of [target('22.16.1', 'darwin', 'arm64'), target('24.1.0', 'darwin', 'arm64'), target('22.16.0')])
27
+ assert.throws(() => assertRuntimeTargetCompatibility(f.manifest, { target: next }), { code: 'RUNTIME_TARGET_UNSUPPORTED' });
28
+ const changed = structuredClone(f.manifest); changed.targets[0].nodeVersion = '24.1.0';
29
+ assert.throws(() => validateRuntimeManifest(changed), { code: 'INVALID_RUNTIME_COMPATIBILITY' });
30
+ });
31
+
32
+ test('versioned declarations consume exact observed targets without supporting undeclared Node majors or platforms', async () => {
33
+ const f = declared(), samples = [];
34
+ const read = verifyRuntimeManifest(f.bytes, f.manifestHash);
35
+ assert.deepEqual(decodeRuntimeArchive(f.archive, read), f.entries);
36
+ for (const [next, accepted] of [[target('22.16.0'), true], [target('22.16.1'), true], [target('22.99.0'), true],
37
+ [target('22.15.99'), false], [target('24.0.99'), false], [target('24.1.0'), true], [target('24.2.0'), true],
38
+ [target('23.0.0'), false], [target('25.0.0'), false], [target('24.1.0', 'linux', 'arm64'), false],
39
+ [target('24.1.0', 'darwin', 'x64'), false], [target('24.1.0', 'win32'), false]]) {
40
+ if (accepted) {
41
+ assert.equal(assertRuntimeTargetCompatibility(read, { target: next }), true);
42
+ assert.equal(assertRuntimeCompatibility(read, { target: next, expected: f.expected }), true);
43
+ assert.equal(verifyRuntimePair(read, f.lock, f.expected, { target: next }).ready, false);
44
+ } else assert.throws(() => assertRuntimeTargetCompatibility(read, { target: next }), { code: 'RUNTIME_TARGET_UNSUPPORTED' });
45
+ samples.push({ target: next, accepted, code: accepted ? null : 'RUNTIME_TARGET_UNSUPPORTED' });
46
+ }
47
+ if (process.env.CHRONA_RUNTIME_TARGET_VECTOR_OUTPUT) await writeFile(process.env.CHRONA_RUNTIME_TARGET_VECTOR_OUTPUT,
48
+ JSON.stringify({ fixtureOnly: true, nativeRuntimeVerified: false, manifest: read, manifestBytesBase64: f.bytes.toString('base64'),
49
+ manifestSha256: f.manifestHash, lock: f.lock, expected: f.expected, samples }, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
50
+ });
51
+
52
+ test('actual target format is independent of support and excludes coerced, prerelease and malformed versions', () => {
53
+ const f = declared();
54
+ for (const value of ['22.16.0', '24.1.0', '25.0.0']) assert.equal(validateRuntimeTarget(target(value)), true);
55
+ for (const value of ['v24.1.0', '24.1', '24.1.0-rc.1', '24.1.0+build', '024.1.0', '24.01.0', '24.1.0\n', '0.1.0',
56
+ '9007199254740992.0.0', null, 24]) {
57
+ assert.equal(validateRuntimeTarget(target(value)), false);
58
+ assert.throws(() => assertRuntimeTargetCompatibility(f.manifest, { target: target(value) }), { code: 'RUNTIME_TARGET_UNSUPPORTED' });
59
+ }
60
+ for (const value of [null, {}, { ...target('24.1.0'), engines: '>=22' }, { ...target('24.1.0'), arch: 'ARM64' }])
61
+ assert.equal(validateRuntimeTarget(value), false);
62
+ });
63
+
64
+ test('bad or unknown declarations cannot fall back to an exact target or engines', () => {
65
+ const mutations = [r => { r.nodeSupport.schemaVersion = '2.0.0'; }, r => { r.nodeSupport.lines = []; },
66
+ r => { r.nodeSupport.lines[0].major = 24; }, r => { r.nodeSupport.lines.reverse(); },
67
+ r => { r.nodeSupport.lines.push(r.nodeSupport.lines[1]); }, r => { r.nodeSupport.lines[0].maximum = '99'; },
68
+ r => { r.nodeSupport.engines = '>=22'; }, r => { r.nodeVersion = '22.16.0'; }, r => { r.os = 'win32'; },
69
+ r => { r.nodeSupport.lines[0].minimum = '22.16.0\n'; }];
70
+ for (const mutate of mutations) {
71
+ const f = declared(); mutate(f.manifest.targets[0]); seal(f);
72
+ assert.throws(() => assertRuntimeTargetCompatibility(f.manifest, { target: target('22.16.0') }), { code: 'INVALID_RUNTIME_COMPATIBILITY' });
73
+ }
74
+ });
75
+
76
+ test('target support never overrides content, canonical manifest, pair hashes or public-untrusted tier', () => {
77
+ const f = declared(), next = target('24.1.0');
78
+ const expected = structuredClone(f.expected); expected.tool.packageVersion = '9.9.9';
79
+ assert.throws(() => assertRuntimeCompatibility(f.manifest, { target: next, expected }), { code: 'RUNTIME_CONTENT_INCOMPATIBLE' });
80
+ assert.throws(() => assertRuntimeCompatibility(f.manifest, { target: target('25.0.0'), expected }), { code: 'RUNTIME_TARGET_UNSUPPORTED' });
81
+ const changed = structuredClone(f.manifest); changed.targets[0].nodeSupport.lines[1].minimum = '24.2.0';
82
+ assert.throws(() => validateRuntimeManifest(changed), { code: 'RUNTIME_PACKAGE_IDENTITY_MISMATCH' });
83
+ const badLock = structuredClone(f.lock); badLock.manifest.sha256 = runtimeHash('wrong');
84
+ assert.throws(() => verifyRuntimePair(f.manifest, badLock, f.expected, { target: next }), { code: 'RUNTIME_PAIR_MISMATCH' });
85
+ const privateManifest = structuredClone(f.manifest); privateManifest.executionTier = 'trusted';
86
+ assert.throws(() => assertRuntimeTargetCompatibility(privateManifest, { target: next }), { code: 'INVALID_RUNTIME_MANIFEST' });
87
+ });
88
+
89
+ test('schema keeps old declaration and IPC observed target separate from versioned support', async () => {
90
+ const schema = JSON.parse(await readFile(new URL('./runtime-manifest.schema.json', import.meta.url)));
91
+ assert.equal(schema.$defs.legacyTarget.properties.nodeVersion.const, '22.16.0');
92
+ assert.equal(schema.$defs.supportedTarget.properties.nodeSupport.properties.schemaVersion.const, '1.0.0');
93
+ const shape = schema.$defs.observedTarget;
94
+ assert.deepEqual(shape.required.sort(), ['arch', 'nodeVersion', 'os']);
95
+ const pattern = new RegExp(shape.properties.nodeVersion.pattern);
96
+ for (const value of ['22.16.0', '24.1.0', '25.0.0']) assert.equal(pattern.test(value), true);
97
+ for (const value of ['024.1.0', '24.1.0\n', 'v24.1.0', '24.1.0-rc.1', '0.1.0']) assert.equal(pattern.test(value), false);
98
+ });
@@ -1,7 +1,8 @@
1
1
  # Conversational creation with the installed Chrona Kit
2
2
 
3
- This is the English creator guide for the Kit 1.5.9 candidate, not a finalized
4
- release. The issued Kit 1.5.8 archive remains unchanged. Use the installed
3
+ This is the current English creator source guide. The issued Kit 1.5.9 archive
4
+ and earlier 1.5.8 archive remain unchanged; source corrections do not rewrite
5
+ their bundled guides. Use the installed
5
6
  `chrona` CLI and its registered MCP server, not an arbitrary development checkout.
6
7
  Installing the Kit, authorizing the platform, uploading source, checking a
7
8
  preview and explicitly publishing are separate operations. None proves the next
@@ -10,17 +11,59 @@ because this guide changed.
10
11
 
11
12
  ## Initialize once, preserve existing work
12
13
 
13
- For the deployed Testing archive, run this once inside your work directory:
14
+ <!-- creator-entry:start -->
15
+ <!-- Generated by tools/creator-entry-docs.mjs from the existing release profiles. -->
16
+ Inside the intended work directory, use the Testing npm entry:
14
17
 
15
18
  ```sh
16
- npx --yes --ignore-scripts https://18.145.213.118/site-assets/chrona-kit.tgz init
19
+ npx @chrona-city/ugc-kit@testing init
17
20
  ```
18
21
 
19
- This downloads the issued archive without an npm publication. The alias is only
20
- discovery: the original installer still verifies the current and immutable
21
- metadata, complete archive and caller bytes. Installing does not authorize an
22
- upload, execute a model or publish a work. The shipped package's declared desktop
23
- target and Node/Git/npm prerequisites still apply.
22
+ The selected package defaults to **https://chrona.city** and discovers
23
+ `/site-assets/chrona-kit-current.json`. Initialization still verifies the current and immutable
24
+ metadata, exact archive and caller. npm publication alone does not prove that
25
+ the platform's download aliases, current tool policy or ordinary user flow are ready.
26
+
27
+ | Release profile | Package identity | Default platform Origin |
28
+ | --- | --- | --- |
29
+ | city | `@chrona-city/ugc-kit` | https://chrona.city |
30
+ | world | `@chrona-world/ugc-kit` | https://chrona.world |
31
+
32
+ The world row describes a separate release profile, not a public rollout claim.
33
+ npm tags select package versions; they do not change an existing project's
34
+ platform, World, permissions or private authorization. Keep existing bindings.
35
+ Local initialization must explicitly select the registered loopback platform;
36
+ it never falls back to Testing. MCP uses the verified persistent executable,
37
+ not a mutable npm tag. Installing does not authorize, upload, preview or publish a work.
38
+
39
+ Both the website archive and npm entry must resolve to the same verified release
40
+ identity. A newer npm package does not silently replace an existing MCP executable,
41
+ project binding or authorization session. Check the actual registered executable
42
+ with `chrona version`, and inspect the saved session without changing it:
43
+
44
+ ```sh
45
+ chrona auth-status --session-directory ABSOLUTE_PRIVATE_SESSION_DIRECTORY
46
+ ```
47
+
48
+ For the city profile, the returned authorization Origin and the project's
49
+ authorization, submission, review and preview links must use https://chrona.city.
50
+ If an older registration or session still selects another Origin, preserve its
51
+ receipts and unknown operations. `--replace-from` only updates the same binding;
52
+ it does not migrate a session across Origins. Select the intended platform
53
+ explicitly, complete its official authorization yourself, then verify access to
54
+ the same project before writing. Do not edit session JSON, rewrite a project ID,
55
+ re-upload content or switch accounts to hide the mismatch. The installer never
56
+ performs these authorization or submission steps automatically.
57
+
58
+ Installation metadata lists verified installation targets, not every CPU binary
59
+ bundled in the archive. Its Node version records the build environment; Runtime
60
+ support must come from the trusted Runtime declaration and real execution.
61
+ <!-- creator-entry:end -->
62
+
63
+ The shipped package's declared desktop target and Node/Git/npm prerequisites
64
+ still apply. A platform-provided archive is an alternative only when its
65
+ actual release metadata and immutable bytes are verified; old IP aliases are
66
+ historical distribution addresses, not the default for a new city installation.
24
67
 
25
68
  Run `chrona init` from the selected project directory. The installed package's
26
69
  `creator-release.json` supplies official release defaults. The CLI checks the
@@ -35,10 +78,10 @@ registration must be resolved explicitly, not overwritten. A `selection-required
35
78
  result asks for the missing workspace or Harness choice. Do not register an
36
79
  entire home directory or move a user's project to make initialization pass.
37
80
 
38
- ### Explicit local initialization (source repair, not in the issued 1.5.8 archive)
81
+ ### Explicit local initialization (not in the issued 1.5.8 archive)
39
82
 
40
- The original persistent installer now accepts `--platform
41
- http://127.0.0.1:8137 --allow-local-http true` in this source candidate. It reads
83
+ The 1.5.9 persistent installer accepts `--platform
84
+ http://127.0.0.1:8137 --allow-local-http true`. It reads
42
85
  that Origin's fixed `/site-assets/chrona-kit-current.json`, requires its
43
86
  same-Origin immutable metadata and archive, and registers local runtime
44
87
  transport with the same Origin and package-pinned catalog. A missing local
@@ -1,5 +1,62 @@
1
1
  # Portable creator package
2
2
 
3
+ ## Current creator entry
4
+
5
+ <!-- creator-entry:start -->
6
+ <!-- Generated by tools/creator-entry-docs.mjs from the existing release profiles. -->
7
+ Inside the intended work directory, use the Testing npm entry:
8
+
9
+ ```sh
10
+ npx @chrona-city/ugc-kit@testing init
11
+ ```
12
+
13
+ The selected package defaults to **https://chrona.city** and discovers
14
+ `/site-assets/chrona-kit-current.json`. Initialization still verifies the current and immutable
15
+ metadata, exact archive and caller. npm publication alone does not prove that
16
+ the platform's download aliases, current tool policy or ordinary user flow are ready.
17
+
18
+ | Release profile | Package identity | Default platform Origin |
19
+ | --- | --- | --- |
20
+ | city | `@chrona-city/ugc-kit` | https://chrona.city |
21
+ | world | `@chrona-world/ugc-kit` | https://chrona.world |
22
+
23
+ The world row describes a separate release profile, not a public rollout claim.
24
+ npm tags select package versions; they do not change an existing project's
25
+ platform, World, permissions or private authorization. Keep existing bindings.
26
+ Local initialization must explicitly select the registered loopback platform;
27
+ it never falls back to Testing. MCP uses the verified persistent executable,
28
+ not a mutable npm tag. Installing does not authorize, upload, preview or publish a work.
29
+
30
+ Both the website archive and npm entry must resolve to the same verified release
31
+ identity. A newer npm package does not silently replace an existing MCP executable,
32
+ project binding or authorization session. Check the actual registered executable
33
+ with `chrona version`, and inspect the saved session without changing it:
34
+
35
+ ```sh
36
+ chrona auth-status --session-directory ABSOLUTE_PRIVATE_SESSION_DIRECTORY
37
+ ```
38
+
39
+ For the city profile, the returned authorization Origin and the project's
40
+ authorization, submission, review and preview links must use https://chrona.city.
41
+ If an older registration or session still selects another Origin, preserve its
42
+ receipts and unknown operations. `--replace-from` only updates the same binding;
43
+ it does not migrate a session across Origins. Select the intended platform
44
+ explicitly, complete its official authorization yourself, then verify access to
45
+ the same project before writing. Do not edit session JSON, rewrite a project ID,
46
+ re-upload content or switch accounts to hide the mismatch. The installer never
47
+ performs these authorization or submission steps automatically.
48
+
49
+ Installation metadata lists verified installation targets, not every CPU binary
50
+ bundled in the archive. Its Node version records the build environment; Runtime
51
+ support must come from the trusted Runtime declaration and real execution.
52
+ <!-- creator-entry:end -->
53
+
54
+ The published 1.5.9 archive remains immutable. These source-guide corrections
55
+ do not rewrite its bundled documentation. Historical versions and tool hashes
56
+ below describe compatibility history, not a request to downgrade, recreate a
57
+ project or change its platform. Package availability and platform availability
58
+ must be checked separately.
59
+
3
60
  ### Bind an imported Document to ordinary Creator authoring
4
61
 
5
62
  `import-presentation` prepares the original editable HTML/resources and a fixed
@@ -83,7 +140,7 @@ download minimum or a promise about another network. Reordering the same require
83
140
  download or omitting the binary does not establish a faster usable first install.
84
141
  Warm-cache and repeat-init measurements must remain separate from cold results.
85
142
 
86
- This unissued candidate bundles all six production dependency roots and their
143
+ The package bundles all six production dependency roots and their
87
144
  locked transitive dependencies, including Darwin ARM64 and Linux ARM64 esbuild.
88
145
  Development dependencies, complete City assets and the separately pinned gameplay
89
146
  runtime are not part of the npm archive. Bundling a Linux binary does not itself
@@ -112,15 +169,31 @@ the user's Home or projects.
112
169
 
113
170
  This source candidate supports `chrona init` from the intended project directory. Bundled `creator-release.json` supplies the official Testing Origin and stable release metadata URL; neither project files nor routine user input supply release hashes/URLs. The installer checks the stable metadata against its same-origin immutable copy, verifies archive bytes and caller identity, and preserves the existing durable installation and AI configuration. Home/root and ambiguous launch folders require a project choice; ambiguous AI detection requires `--harness codex|claude`. Interactive terminals ask these choices; noninteractive callers receive `selection-required`. Explicit advanced options remain available. Init does not create, upgrade or overwrite content.
114
171
 
115
- After the matching Site release exposes the stable aliases, the Testing entry is `npm exec --yes --ignore-scripts --no-audit --no-fund --no-update-notifier --package https://18.145.213.118/site-assets/chrona-kit.tgz -- chrona init`. This is not live merely because source code or a local pack passes. Only after separately authorized npm publication may testers use `npx @chrona/ugc-kit@1.3.0 init`; the `latest` channel must not point to an unverified candidate. The MCP config uses the fixed persistent executable, never a mutable npm tag. Original immutable download commands remain specific to their exact previously issued archives.
116
-
117
- The current source repair candidate is `@chrona/ugc-kit@1.5.3`; the issued `v1.5.2` source, archive and Tag remain unchanged. The issued 1.5.2 archive does not contain the historical-project compatibility repair; isolated development archives with that version text are not user releases. This candidate needs a catalog whose Darwin ARM64 and Linux ARM64 entries match its exact tool version and snapshot identity before final release verification. Until that pairing and release verification are complete, source version 1.5.3 is not a user download or published npm release. Its default original Testing platform Origin is `https://18.145.213.118`; the runtime catalog must separately pin four verified URLs at that Origin. Distribution still requires verified files at the selected origin and installation checks against the exact final archive. Use the explicitly registered local runtime source for local delivery; canonical HTTPS catalog URLs are not evidence of Testing deployment. npm registry publication is separate from creator content submission, independent review and platform publication. A fixed archive can be installed without a registry release; this does not disable `submit` or `publish --channel testing`. Those commands still require actual authorization and matching platform validation. The package does not grant an open-source license (`UNLICENSED`).
172
+ Use the profile-derived entry at the top of this guide. The selected package's
173
+ `creator-release.json` supplies its default Origin and release metadata path;
174
+ schema3 `kit-release.json` supplies the actual package/version/archive identity.
175
+ Site must derive presentation from those verified fields, not maintain a second
176
+ package/domain mapping or infer an environment from an npm tag. A metadata
177
+ endpoint failure or incompatible caller is a concrete installation failure,
178
+ not permission to silently install an older release. MCP uses the fixed persistent
179
+ executable. Its presence does not prove the user's model has called the tools.
180
+
181
+ Historical 1.5.2/1.5.3 archives, old IP aliases and legacy package names remain
182
+ specific to their original immutable releases. They are not current default
183
+ installation examples and must not be edited in place. Use the actual installed
184
+ catalog and runtime manifests for compatibility; URLs alone do not prove a
185
+ platform deployment. npm publication, creator source submission, preview and
186
+ explicit publication are separate. The package remains `UNLICENSED`.
118
187
 
119
188
  Optional [Meshy generation](meshy.md) uses your local key and explicit requests. New installation and explicit same-scope Harness replacement use the existing `init`; `--replace-from /absolute/old-install/bin/chrona.mjs` authorizes replacing only that exact existing registration. Workspace, platform and session scope must remain identical; edited/unmanaged configurations reject. No silent update occurs. Project metadata migration remains a separate `upgrade` operation. Credentials in the private user directory are not part of either installation.
120
189
 
121
190
  Runtime compatibility is determined by the project's tool/contracts locks, the trusted catalog's verified manifests and the packaged host identity. Read actual `dev/test` results; do not infer that the platform supports only an older tool version, or that every new project is compatible. `RUNTIME_CONTENT_INCOMPATIBLE` requires a matching fixed runtime or an explicitly approved project migration, not editing locks or downgrading a version label. Changing only the external runtime manifest cannot add host support. Do not modify an existing archive or report a new snapshot as an older tool version. A local tarball install is not a registry publication or a playable-content acceptance. Node 22.16 or later and Git are required. There are no install hooks or runtime downloads at installation. The original static compiler dependencies are pinned; npm may fetch those packages during installation, but does not run their hooks with the commands below.
122
191
 
123
- In a separate tools directory, install the fixed `.tgz` supplied for evaluation using `npm install --ignore-scripts /absolute/path/chrona-ugc-kit-1.3.0-alpha.1.2.tgz`. Invoke the local binary from that directory with `npm exec --offline -- chrona`; no Services or Clients checkout is required:
192
+ For an explicitly selected fixed-archive alternative, use a separate tools
193
+ directory and `npm install --ignore-scripts /absolute/path/verified-ugc-kit.tgz`.
194
+ The file must be the release's verified archive, not a development pack. Invoke
195
+ the local binary from that directory with `npm exec --offline -- chrona`; no
196
+ Services or Clients checkout is required:
124
197
 
125
198
  ```sh
126
199
  npm exec --offline -- chrona create my-world --content-id ugc.example.my-world --workspace /existing/creator/projects
@@ -131,9 +204,15 @@ npm exec --offline -- chrona capabilities
131
204
 
132
205
  This source candidate also exposes `chrona projects --workspace /existing/creator/projects` and the read-only MCP `list_ugc_projects`. The MCP uses its registered workspace, so conversational callers supply no local path. Results include the configured project itself as `projectName: "."` and initialized direct-child projects, with explicit unavailable metadata; they never select a project, prove source access, or start a runtime. The dot cannot refer to a parent or sibling directory. With platform authorization configured, `list_creator_materials` lists the selected platform project's currently authorized materials; `create_from_creator_material` downloads and verifies the selection and creates a new isolated project. The fixed earlier 0.2.13 installation does not contain these additions.
133
206
 
134
- The creator project contains content and small metadata only. In that project, use `npm install --ignore-scripts --no-save --package-lock=false /absolute/path/chrona-ugc-kit-1.3.0-alpha.1.2.tgz` to install this unpublished candidate without replacing the fixed dependency with a local path. Then use `npm run validate` and resolve `#chrona/shared` / `#chrona/client` through the installed SDK. The exact tool version and snapshot digest are pinned in `chrona.toolchain.json`; incompatible tools fail instead of selecting latest. Neither metadata nor SDK resolution grants execution permission. The platform revalidates with its own trusted Kit.
207
+ The creator project contains content and small metadata only. Its exact package
208
+ dependency, SDK import mappings and `chrona.toolchain.json` retain their original
209
+ identity. Use the normal initialized project commands; do not edit an existing
210
+ lock, replace a dependency with a local archive path or install latest to suppress
211
+ a mismatch. Inspect the explicit `chrona upgrade` plan when a supported migration
212
+ is needed. Neither metadata nor SDK resolution grants execution permission. The
213
+ platform revalidates with its own trusted Kit.
135
214
 
136
- Trusted local hosts can import `verifyLocalDevelopmentInput` and `validateLocalLaunchRequest` from `@chrona/ugc-kit/local-content`. The snapshot and launch definitions are in `contracts/ugc/local-content/v1/README.md` and `LOCAL-LAUNCH.md`; seven files are bound by `local-content.snapshot.lock.json` and the project toolchain hash. The sandbox contract snapshot is 1.2.0. The trusted public host selects local launch validation; formal execution continues to reject local identities. These exports verify offline inputs; scene compilation uses `build` below and execution requires a separately trusted runtime. Verification requires host-owned reads, a fixed expected identity and trusted policy hashes. Local validation does not grant formal review, preview membership or publication.
215
+ Trusted local hosts import `verifyLocalDevelopmentInput` and `validateLocalLaunchRequest` from the selected installed package's `/local-content` export. Resolve its package name from actual installed `package.json`, not a second scope list. Historical legacy projects keep their own exact identity. The snapshot and launch definitions are in `contracts/ugc/local-content/v1/README.md` and `LOCAL-LAUNCH.md`; the exact inventory is bound by `local-content.snapshot.lock.json` and the project toolchain hash. The trusted public host selects local launch validation; formal execution continues to reject local identities. These exports verify offline inputs; scene compilation uses `build` below and execution requires a separately trusted runtime. Verification requires host-owned reads, a fixed expected identity and trusted policy hashes. Local validation does not grant formal review, preview membership or publication.
137
216
 
138
217
  Static validate never imports creator JavaScript. Repair its structured errors and rerun. Missing required capabilities return `needs_capability` with exit code 2. Failed validation returns 1; passed returns 0. The public tool rejects reviewed-tier projects. `publish` requests independent review only; there is no native creator execution or automatic approval/publication fallback.
139
218
 
@@ -157,7 +236,7 @@ Only a complete zero-match result with `canCreateProject:true` permits offering
157
236
 
158
237
  The AI validates the work, preserves intentional changes and makes the requested real source commit. Submit through the original MCP/CLI with `expectedHead` and `idempotencyKey` omitted by default: the tool obtains or reuses the verified head, derives the key and retains both in `build/creator-upload.json`. An unchanged retry preserves the original operation; a conflict requires inspecting current source state, not forcing `none` or deleting the record. `get_creator_preflight` exposes current platform compatibility and release eligibility; submit also checks preflight before uploading. Return the actual job/Studio link and state. Uploaded or queued is not reviewed, published or playable. Preview and `publish --channel testing` request separate platform steps; npm registry availability is not their gate. Earlier fixed archives require their own supported explicit parameters and do not acquire this behavior automatically.
159
238
 
160
- ### 1.5 candidate submission slice (source only; not distributed)
239
+ ### Contribution candidates (separate from owner submission)
161
240
 
162
241
  The separate contribution candidate interface requires an existing project and a project-bound terminal authorization with `projects:read,source:read,contributions:write`. The default owner six-scope login does not include candidate write. Use `chrona login --platform ORIGIN --session-directory PRIVATE_DIR --project-id PROJECT_ID --scopes projects:read,source:read,contributions:write`, then the normal browser approval and `login-complete`. After committing a clean local work, run `chrona contribute --session-directory PRIVATE_DIR --project DIR --project-id PROJECT_ID` (optionally pin `--expected-head MAIN_SHA` and `--idempotency-key KEY`). The CLI reads the current main source head, uploads committed content through the distinct candidate blob namespace and persists the key in `build/creator-contribution.json`, never `build/creator-upload.json`.
163
242
 
@@ -171,10 +250,14 @@ When another contribution advances main, use `chrona project-source-update --ses
171
250
 
172
251
  ### Continue a work from an earlier fixed toolchain
173
252
 
174
- Source candidates containing `chrona upgrade` can explicitly migrate the fixed
175
- 0.2.13/e24f4d5d and 0.2.14/ac0cb216, bed80a0f, 334894a4 or 1c996822 toolchains, plus 1.3.0-alpha.1, 1.3.0-alpha.1.1 and 1.3.0-alpha.1.2/1d15d99b, and 1.3.0-alpha.1.3, 1.3.0-alpha.1.4 or 1.3.0-alpha.1.5/a7cde603, and 1.3.0/a7cde603, 1.4.0/a7cde603 or 1.5.0/a7cde603 or 1.5.1/a7cde603 or 1.5.2/a7cde603, to the installed 1.5.3/a7cde603 source candidate. The destination is an exact tool/contracts identity, not merely a matching package version. Content must pass the destination static contract; a successful metadata upgrade does not prove the work's runtime or platform eligibility. Previously distributed archives do
176
- not acquire this command. Check the installed `help` and the exact archive supplied
177
- by the platform; do not overwrite an old archive or install latest automatically.
253
+ `chrona upgrade` plans against the actual installed package/tool/contracts
254
+ identity and its registered historical-source compatibility rules. Read the
255
+ returned plan; neither a numeric version range nor a documentation list grants
256
+ compatibility. Historical identities and SDK mappings remain protected in the
257
+ original resolver. Content must pass the destination static contract; a metadata
258
+ upgrade does not prove Runtime or platform eligibility. Earlier archives do not
259
+ gain newer migration rules automatically. Do not overwrite an old archive or
260
+ install latest merely to bypass a source/toolchain mismatch.
178
261
 
179
262
  The Testing review snapshot uses explicit source-declaration acceptance and technical
180
263
  inspection results, not independent copyright clearance or general image moderation.