@chrona-city/ugc-kit 1.5.9 → 1.5.10

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 (31) hide show
  1. package/README.md +79 -5
  2. package/contracts/ugc/public-runtime/v1/README.md +42 -5
  3. package/contracts/ugc/public-runtime/v1/manifest.mjs +35 -4
  4. package/contracts/ugc/public-runtime/v1/runtime-manifest.schema.json +126 -23
  5. package/contracts/ugc/public-runtime/v1/target-compatibility.test.mjs +98 -0
  6. package/docs/harness-onboarding.md +55 -12
  7. package/docs/npm-creator.md +95 -12
  8. package/docs/runtime-download.md +43 -2
  9. package/lib/creator-cli.mjs +6 -4
  10. package/lib/creator-platform.mjs +2 -1
  11. package/lib/creator-toolchain-compat.mjs +3 -0
  12. package/lib/host-ipc/distribution-node-support-contract/contracts/ugc/public-runtime/v1/manifest.mjs +198 -0
  13. package/lib/host-ipc/distribution-node-support-contract/contracts/ugc/public-runtime/v1/runtime-manifest.schema.json +854 -0
  14. package/lib/host-ipc/distribution-node-support-contract/contracts/ugc/registry/v1/conformance/js/capability-resolver.mjs +191 -0
  15. package/lib/host-ipc/host-ipc.schema.json +2 -27
  16. package/lib/host-ipc/runtime-contract.mjs +7 -3
  17. package/lib/host-ipc/source-lock.json +16 -4
  18. package/lib/local-development.mjs +5 -2
  19. package/lib/runtime-host-client.mjs +1 -0
  20. package/lib/runtime-host.mjs +10 -3
  21. package/lib/runtime-install.mjs +1 -0
  22. package/node_modules/@esbuild/darwin-x64/README.md +3 -0
  23. package/node_modules/@esbuild/darwin-x64/bin/esbuild +0 -0
  24. package/node_modules/@esbuild/darwin-x64/package.json +20 -0
  25. package/node_modules/@esbuild/linux-x64/README.md +3 -0
  26. package/node_modules/@esbuild/linux-x64/bin/esbuild +0 -0
  27. package/node_modules/@esbuild/linux-x64/package.json +20 -0
  28. package/package.json +1 -1
  29. package/public-runtime.snapshot.lock.json +8 -4
  30. package/runtime-catalog.json +8 -24
  31. /package/lib/host-ipc/{distribution-document-tool-package-contract → distribution-node-support-contract}/contracts/ugc/creator-source/v1/tool-package.schema.json +0 -0
package/README.md CHANGED
@@ -16,7 +16,63 @@ mirror through the original `init`/MCP and `dev/test` options. Only transport ch
16
16
  package-pinned runtime bytes and compatibility checks remain enforced, with no
17
17
  Testing fallback. See [runtime sources](docs/runtime-download.md#explicit-local-distribution-same-pinned-runtime-bytes).
18
18
 
19
- The current unfinalized candidate is `@chrona/ugc-kit@1.5.8`; historical issued source, Tags and archives remain unchanged. It retains the trusted historical-project compatibility resolver used by project download and update. Earlier development archives are not interchangeable with issued archives. See [the npm creator guide](docs/npm-creator.md) for `chrona init/create/validate`, conversational authorization and the bundled MCP entrypoints, and [Meshy](docs/meshy.md) for optional local asset generation with your own key. Use the platform's exact archive identity; local pack/install evidence is not npm registry publication. npm distribution and creator content submission/review/publication are separate paths. Runtime compatibility and platform availability are checked against actual pinned manifests and API results, not inferred from this README. The repository-development and reviewed local workflows below are separate from the public npm command surface; the public binary never calls their native creator-JavaScript tests.
19
+ ## Creator entry
20
+
21
+ <!-- creator-entry:start -->
22
+ <!-- Generated by tools/creator-entry-docs.mjs from the existing release profiles. -->
23
+ Inside the intended work directory, use the Testing npm entry:
24
+
25
+ ```sh
26
+ npx @chrona-city/ugc-kit@testing init
27
+ ```
28
+
29
+ The selected package defaults to **https://chrona.city** and discovers
30
+ `/site-assets/chrona-kit-current.json`. Initialization still verifies the current and immutable
31
+ metadata, exact archive and caller. npm publication alone does not prove that
32
+ the platform's download aliases, current tool policy or ordinary user flow are ready.
33
+
34
+ | Release profile | Package identity | Default platform Origin |
35
+ | --- | --- | --- |
36
+ | city | `@chrona-city/ugc-kit` | https://chrona.city |
37
+ | world | `@chrona-world/ugc-kit` | https://chrona.world |
38
+
39
+ The world row describes a separate release profile, not a public rollout claim.
40
+ npm tags select package versions; they do not change an existing project's
41
+ platform, World, permissions or private authorization. Keep existing bindings.
42
+ Local initialization must explicitly select the registered loopback platform;
43
+ it never falls back to Testing. MCP uses the verified persistent executable,
44
+ not a mutable npm tag. Installing does not authorize, upload, preview or publish a work.
45
+
46
+ Both the website archive and npm entry must resolve to the same verified release
47
+ identity. A newer npm package does not silently replace an existing MCP executable,
48
+ project binding or authorization session. Check the actual registered executable
49
+ with `chrona version`, and inspect the saved session without changing it:
50
+
51
+ ```sh
52
+ chrona auth-status --session-directory ABSOLUTE_PRIVATE_SESSION_DIRECTORY
53
+ ```
54
+
55
+ For the city profile, the returned authorization Origin and the project's
56
+ authorization, submission, review and preview links must use https://chrona.city.
57
+ If an older registration or session still selects another Origin, preserve its
58
+ receipts and unknown operations. `--replace-from` only updates the same binding;
59
+ it does not migrate a session across Origins. Select the intended platform
60
+ explicitly, complete its official authorization yourself, then verify access to
61
+ the same project before writing. Do not edit session JSON, rewrite a project ID,
62
+ re-upload content or switch accounts to hide the mismatch. The installer never
63
+ performs these authorization or submission steps automatically.
64
+
65
+ Installation metadata lists verified installation targets, not every CPU binary
66
+ bundled in the archive. Its Node version records the build environment; Runtime
67
+ support must come from the trusted Runtime declaration and real execution.
68
+ <!-- creator-entry:end -->
69
+
70
+ See [Harness onboarding](docs/harness-onboarding.md) for Codex/Claude registration,
71
+ [the npm creator guide](docs/npm-creator.md) for the installed CLI and contribution
72
+ workflow, and [Meshy](docs/meshy.md) for optional local asset generation. Already
73
+ issued archives and Tags remain immutable. This source documentation correction
74
+ does not change the guides inside the published 1.5.9 archive. Historical package
75
+ identities remain valid historical identities, not instructions to rename projects.
20
76
 
21
77
  Chrona UGC Kit provides versioned project conventions, validation tools, templates, and contract snapshots used by AI agents and creator harnesses to build content for Chrona.
22
78
 
@@ -25,9 +81,10 @@ The creator protocol is reviewed outside this repository first. Only an approved
25
81
  Paired scene/compiler updates use the existing `tools/sync-local-content.mjs`
26
82
  entry with a fixed Services commit and trusted compiler export. See
27
83
  [snapshot sync](tools/snapshot-sync.md) for the exact command and failure boundaries.
28
- The 1.5.3 internal candidate retains the a7cde603 tool snapshot and
29
- 9f984cbb scene-report identity. Its catalog pairs Darwin ARM64 and Linux ARM64
30
- runtimes only after both target manifests name this exact version. Select the explicitly registered local runtime
84
+ The historical 1.5.3 internal candidate retained the a7cde603 tool snapshot and
85
+ 9f984cbb scene-report identity. Current compatibility comes from the actual
86
+ installed tool/contracts and verified manifests, not those historical labels.
87
+ Select the explicitly registered local runtime
31
88
  origin for local delivery; canonical HTTPS URLs do not prove Testing deployment.
32
89
  Do not relabel any already distributed alpha archive. Installation, native
33
90
  dependency execution, gameplay and platform publication remain separate checks.
@@ -36,7 +93,14 @@ This repository does not contain player projects or Chrona production credential
36
93
 
37
94
  ## Release verification
38
95
 
39
- This candidate targets 1.5.3, but is not a verified, distributed release until its paired catalog, immutable archive and tag are finalized. Accepted versions are `M.m.p`, `M.m.p-alpha.N` and `M.m.p-alpha.N.P`, with positive, non-zero-prefixed alpha numbers. The full suffix remains part of every tool identity. `publishConfig.tag` must be `alpha` for prereleases and `latest` for stable releases; this validation does not publish or change an npm channel.
96
+ This section is for maintainers, not creator onboarding. The single-profile
97
+ examples below retain historical release arguments; they must not be replayed
98
+ to modify an issued version. City/world packaging selects the original
99
+ `--release-profile` and versioned `tools/release-profiles.json`; it does not create
100
+ environment-specific source Tags. Accepted versions are `M.m.p`, `M.m.p-alpha.N`
101
+ and `M.m.p-alpha.N.P`, with positive, non-zero-prefixed alpha numbers. The full
102
+ suffix remains part of every tool identity. Source `publishConfig.tag` validation
103
+ does not publish a package or select the npm dist-tag for an authorized operation.
40
104
 
41
105
  For a version-only follow-up with unchanged implementation evidence, `--test-profile release-identity` runs installation, upgrade, metadata and Harness checks and labels the report with that limited coverage; it is not a full regression. Retain the baseline evidence separately. `--parent-version <fixed-parent>` rejects non-increasing versions; before any authorized channel update, supply the actual current npm target with `--channel-version <current-version>` to reject a numeric downgrade. Do not infer live channel state from a local report.
42
106
 
@@ -65,6 +129,16 @@ Transfer the entire resulting directory and its reported `manifestSha256` throug
65
129
 
66
130
  The export reports both `sourceSha` (the internal runtime producer) and, when present, `finalSourceSha` (the later committed catalog and final Kit package). They can differ without changing the paired runtime bytes; the final evidence must still pin the original pairing/catalog hashes and the final source's package lock. Downstream release-material Readers must validate that lineage rather than assume the two Git commits are identical. Do not edit either proof to satisfy a consumer's one-SHA check.
67
131
 
132
+ For city/world profiles, a fully verified shared Runtime proof can also serve a
133
+ successor creator-tool source when its original versioned execution closure,
134
+ dependency lock and tool/content identity remain unchanged. The original
135
+ Producer, archive, four execution reports and proof keep their identities; the
136
+ catalog Writer and final package each bind their own complete clean source.
137
+ Without that verified proof, the existing exact source checks still apply.
138
+ Dirty/late-changing source, altered execution files, dependency drift or a fake
139
+ proof are not an exemption. Two independently verified OS reports for the same
140
+ manifest and ZIP produce one catalog entry, not an ambiguous duplicate.
141
+
68
142
  The current UGC v1 contract and Capability Registry snapshots are locked to an exact `chrona-services` commit. Verify both with:
69
143
 
70
144
  ```sh
@@ -50,11 +50,48 @@ original source-lock closures; bundling transforms are recorded by that builder,
50
50
  not guessed from output filenames. Private Room/replication/platform code must
51
51
  not be smuggled into a public closure under an allowed name.
52
52
 
53
- `targets` lists exact `{os,arch,nodeVersion}` tuples in canonical-JSON order:
54
- Darwin/Linux, arm64/x64, Node **22.16.0**, at most four. Only actually verified
55
- targets may be advertised; permitting a tuple in the schema is not portability
56
- evidence. Windows and Node minor/patch fallback are not supported. The installer
57
- matches its actual process platform, architecture and Node, not creator input.
53
+ `targets` has at most four declarations in canonical-JSON order. Historical
54
+ `{os,arch,nodeVersion:"22.16.0"}` rows retain exact matching, including the Node
55
+ patch and architecture; their bytes and identities are unchanged. They are not
56
+ reinterpreted as support for another Node or architecture.
57
+
58
+ A new declaration can explicitly separate supported Node lines from precise
59
+ execution observations:
60
+
61
+ ```json
62
+ {"os":"linux","arch":"x64","nodeSupport":{"schemaVersion":"1.0.0","lines":[{"major":22,"minimum":"22.16.0"},{"major":24,"minimum":"24.1.0"}]}}
63
+ ```
64
+
65
+ This is a **shape example, not a verified support claim or catalog artifact**.
66
+ Only an actually validated publisher decision may add these rows to a real
67
+ manifest. `engines.node`, an execution machine's version, a schema acceptance
68
+ test, or portable-looking JS/WASM never creates support. The declaration is
69
+ included in the original Runtime hash, raw manifest pin and trusted lock; this
70
+ Reader does not add it to existing records or rewrite execution reports.
71
+
72
+ `nodeSupport` is exact `{schemaVersion,lines}` with version `1.0.0`. Each of
73
+ one to four lines is exact `{major,minimum}`; majors are positive safe integers
74
+ in strictly increasing order and minimum is a canonical stable `M.m.p` whose
75
+ major equals that line. It supports that major from the minimum onward, up to
76
+ but excluding the next major. No semver expressions, prereleases, automatic
77
+ future majors, OS/arch inference or Windows support. Unknown versions, mixed
78
+ exact/range keys, duplicates and malformed declarations refuse. The existing
79
+ manifest `schemaVersion` still selects static `1.0.0` or Document `1.1.0` content
80
+ layout; it does not select a Node policy.
81
+
82
+ `validateRuntimeTarget(target)` checks only actual observation format:
83
+ exact `{os,arch,nodeVersion}`, Darwin/Linux, arm64/x64 and a positive-major,
84
+ safe-integer stable Node version. `runtime-manifest.schema.json` exposes the
85
+ same shape as `$defs.observedTarget` for IPC transport; this is not a support
86
+ gate. `assertRuntimeTargetCompatibility(manifest,{target})` validates the full
87
+ manifest and applies its declaration. Omitted target uses actual process
88
+ values. It returns `true` or throws the existing `RUNTIME_TARGET_UNSUPPORTED`;
89
+ bad declarations use `INVALID_RUNTIME_COMPATIBILITY`, while manifest/identity
90
+ errors keep their original codes. Host inspect and installed verification must
91
+ use this one API instead of independently comparing `manifest.targets`.
92
+ `assertRuntimeCompatibility` delegates to it, then retains the complete original
93
+ content-row check (`RUNTIME_CONTENT_INCOMPATIBLE`). Precise target/report and
94
+ source/AA/cache proof identities remain precise observations, not range matches.
58
95
 
59
96
  `compatibility` includes protocol 1/2, `content` rows and included
60
97
  local-content validator/world/style policy files. Each of at most eight rows is
@@ -52,8 +52,34 @@ export const runtimeHashFromId = value => {
52
52
  if (typeof value !== 'string' || !/^runtime_[a-f0-9]{64}$/.test(value)) fail('INVALID_RUNTIME_MANIFEST');
53
53
  return `sha256:${value.slice(8)}`;
54
54
  };
55
- const validTarget = v => exact(v, ['os', 'arch', 'nodeVersion']) && ['darwin', 'linux'].includes(v.os)
56
- && ['arm64', 'x64'].includes(v.arch) && v.nodeVersion === '22.16.0';
55
+ // Actual execution observations are exact versions. A support declaration is a
56
+ // separate, versioned manifest value; neither package engines nor a report
57
+ // silently widens it. Old string targets keep their original exact semantics.
58
+ const nodeVersion = v => {
59
+ 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;
60
+ const parts = v.split('.').map(Number);
61
+ return parts.every(Number.isSafeInteger) && parts[0] > 0 ? parts : null;
62
+ };
63
+ const targetPlatform = v => ['darwin', 'linux'].includes(v.os) && ['arm64', 'x64'].includes(v.arch);
64
+ export const validateRuntimeTarget = v => Boolean(exact(v, ['os', 'arch', 'nodeVersion']) && targetPlatform(v) && nodeVersion(v.nodeVersion));
65
+ const validTarget = v => {
66
+ if (exact(v, ['os', 'arch', 'nodeVersion'])) return validateRuntimeTarget(v) && v.nodeVersion === '22.16.0';
67
+ if (!exact(v, ['os', 'arch', 'nodeSupport']) || !targetPlatform(v)
68
+ || !exact(v.nodeSupport, ['schemaVersion', 'lines']) || v.nodeSupport.schemaVersion !== '1.0.0'
69
+ || !Array.isArray(v.nodeSupport.lines) || !v.nodeSupport.lines.length || v.nodeSupport.lines.length > 4) return false;
70
+ return v.nodeSupport.lines.every((line, i, lines) => exact(line, ['major', 'minimum'])
71
+ && Number.isSafeInteger(line.major) && line.major > 0 && nodeVersion(line.minimum)?.[0] === line.major
72
+ && (!i || line.major > lines[i - 1].major));
73
+ };
74
+ const targetMatches = (declared, actual) => {
75
+ if (Object.hasOwn(declared, 'nodeVersion')) return canonicalJson(declared) === canonicalJson(actual);
76
+ const observed = nodeVersion(actual.nodeVersion);
77
+ return declared.os === actual.os && declared.arch === actual.arch && declared.nodeSupport.lines.some(line => {
78
+ if (observed[0] !== line.major) return false;
79
+ const minimum = nodeVersion(line.minimum);
80
+ return observed[1] > minimum[1] || observed[1] === minimum[1] && observed[2] >= minimum[2];
81
+ });
82
+ };
57
83
  // The Host IPC and Runtime compatibility use the same exact tuple definition.
58
84
  // `document` is selected from the verified snapshot/runtime variant, not a
59
85
  // claim made by the child. This validates format, not source approval or access.
@@ -149,9 +175,14 @@ export function validateRuntimeLock(lock, trustedLock, { allowLocalHttp = false
149
175
  return lock;
150
176
  }
151
177
 
152
- export function assertRuntimeCompatibility(manifest, { target = { os: process.platform, arch: process.arch, nodeVersion: process.versions.node }, expected } = {}) {
178
+ export function assertRuntimeTargetCompatibility(manifest, { target = { os: process.platform, arch: process.arch, nodeVersion: process.versions.node } } = {}) {
153
179
  validateRuntimeManifest(manifest);
154
- if (!validTarget(target) || !manifest.targets.some(t => canonicalJson(t) === canonicalJson(target))) fail('RUNTIME_TARGET_UNSUPPORTED');
180
+ if (!validateRuntimeTarget(target) || !manifest.targets.some(t => targetMatches(t, target))) fail('RUNTIME_TARGET_UNSUPPORTED');
181
+ return true;
182
+ }
183
+
184
+ export function assertRuntimeCompatibility(manifest, { target, expected } = {}) {
185
+ assertRuntimeTargetCompatibility(manifest, { target });
155
186
  const row = { builderVersion: expected?.builderVersion, tool: expected?.tool, contracts: expected?.contracts };
156
187
  if (!validContentRow(row, manifest.schemaVersion === '1.1.0') || !manifest.compatibility.content.some(r => canonicalJson(r) === canonicalJson(row))) fail('RUNTIME_CONTENT_INCOMPATIBLE');
157
188
  return true;
@@ -356,31 +356,13 @@
356
356
  }
357
357
  },
358
358
  "target": {
359
- "type": "object",
360
- "additionalProperties": false,
361
- "properties": {
362
- "os": {
363
- "type": "string",
364
- "enum": [
365
- "darwin",
366
- "linux"
367
- ]
368
- },
369
- "arch": {
370
- "type": "string",
371
- "enum": [
372
- "arm64",
373
- "x64"
374
- ]
359
+ "oneOf": [
360
+ {
361
+ "$ref": "#/$defs/legacyTarget"
375
362
  },
376
- "nodeVersion": {
377
- "const": "22.16.0"
363
+ {
364
+ "$ref": "#/$defs/supportedTarget"
378
365
  }
379
- },
380
- "required": [
381
- "os",
382
- "arch",
383
- "nodeVersion"
384
366
  ]
385
367
  },
386
368
  "tool": {
@@ -532,6 +514,127 @@
532
514
  "$ref": "#/$defs/documentContracts"
533
515
  }
534
516
  }
517
+ },
518
+ "legacyTarget": {
519
+ "type": "object",
520
+ "additionalProperties": false,
521
+ "properties": {
522
+ "os": {
523
+ "type": "string",
524
+ "enum": [
525
+ "darwin",
526
+ "linux"
527
+ ]
528
+ },
529
+ "arch": {
530
+ "type": "string",
531
+ "enum": [
532
+ "arm64",
533
+ "x64"
534
+ ]
535
+ },
536
+ "nodeVersion": {
537
+ "const": "22.16.0"
538
+ }
539
+ },
540
+ "required": [
541
+ "os",
542
+ "arch",
543
+ "nodeVersion"
544
+ ]
545
+ },
546
+ "observedTarget": {
547
+ "type": "object",
548
+ "additionalProperties": false,
549
+ "properties": {
550
+ "os": {
551
+ "type": "string",
552
+ "enum": [
553
+ "darwin",
554
+ "linux"
555
+ ]
556
+ },
557
+ "arch": {
558
+ "type": "string",
559
+ "enum": [
560
+ "arm64",
561
+ "x64"
562
+ ]
563
+ },
564
+ "nodeVersion": {
565
+ "type": "string",
566
+ "maxLength": 48,
567
+ "pattern": "^[1-9][0-9]*\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$(?![\\s\\S])"
568
+ }
569
+ },
570
+ "required": [
571
+ "os",
572
+ "arch",
573
+ "nodeVersion"
574
+ ]
575
+ },
576
+ "supportedTarget": {
577
+ "type": "object",
578
+ "additionalProperties": false,
579
+ "required": [
580
+ "os",
581
+ "arch",
582
+ "nodeSupport"
583
+ ],
584
+ "properties": {
585
+ "os": {
586
+ "type": "string",
587
+ "enum": [
588
+ "darwin",
589
+ "linux"
590
+ ]
591
+ },
592
+ "arch": {
593
+ "type": "string",
594
+ "enum": [
595
+ "arm64",
596
+ "x64"
597
+ ]
598
+ },
599
+ "nodeSupport": {
600
+ "type": "object",
601
+ "additionalProperties": false,
602
+ "required": [
603
+ "schemaVersion",
604
+ "lines"
605
+ ],
606
+ "properties": {
607
+ "schemaVersion": {
608
+ "const": "1.0.0"
609
+ },
610
+ "lines": {
611
+ "type": "array",
612
+ "minItems": 1,
613
+ "maxItems": 4,
614
+ "items": {
615
+ "type": "object",
616
+ "additionalProperties": false,
617
+ "required": [
618
+ "major",
619
+ "minimum"
620
+ ],
621
+ "properties": {
622
+ "major": {
623
+ "type": "integer",
624
+ "minimum": 1,
625
+ "maximum": 9007199254740991
626
+ },
627
+ "minimum": {
628
+ "type": "string",
629
+ "maxLength": 48,
630
+ "pattern": "^[1-9][0-9]*\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$(?![\\s\\S])"
631
+ }
632
+ }
633
+ }
634
+ }
635
+ }
636
+ }
637
+ }
535
638
  }
536
639
  },
537
640
  "allOf": [
@@ -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