@forgeax/engine-pack 0.1.23 → 0.1.24

package/README.md

@@ -14,7 +14,13 @@ recook 并重新验证，不手改 cooked payload。
 
 ## Authoring and recovery index
 
-## Parameterized, GUID-less authoring
+## ScriptablePack 与 Pack authoring
+
+> [!IMPORTANT]
+> 这里有两个一等 source 实体，且必须保持可见区别：`ScriptablePack` 是可执行的
+> `*.pack.ts` TypeScript source；`Pack` 是可编辑、可持久化的 `*.pack.json` JSON
+> source。参数化只是 ScriptablePack/Pack instance 的可选能力，不是第三种实体。
+> 构建后的 Pack v2 是 transport 产物；runtime 只按 GUID 加载产物。
 
 The current authoring contract keeps one Pack identity and derives every output
 identity from the author-owned pair `(packageId, sourceKey)`:
@@ -48,7 +54,7 @@ colors, and asset-GUID kind constraints. The build return object is the whole
 current output topology: there is no output manifest, `output.add()`,
 `externalAssets`, or per-output GUID field.
 
-Authoring `pack.json` uses schema `3.0.0`. A direct document stores
+`Pack` authoring (`*.pack.json`) uses schema `3.0.0`. A direct document stores
 `assets[sourceKey]`; an instance stores only its own `packageId`, `parent`, and
 sparse `values`. These branches are mutually exclusive. Every instance has an
 independent package identity, while the parent chain is resolved through the
@@ -57,7 +63,7 @@ transport before runtime; player code still calls `loadByGuid()` and never
 executes TypeScript or understands parameters.
 
 `@forgeax/engine-pack/build` exposes the filesystem gateway
-`createFileSystemParameterizedPackAuthoringGateway()`. Its read operations are
+`createFileSystemPackAuthoringGateway()`. Its read operations are
 `asset.list`, `asset.inspect`, `asset.resolve`, and `asset.verify`; mutations
 are `asset-source.create`, `asset-source.clone`,
 `asset-source.create-instance`, `asset-source.apply-values`,
@@ -224,7 +230,7 @@ root barrel. The root entry remains the build-time scanner/evidence surface.
 
 ## Quick start
 
-### Parameterized ScriptablePack source
+### ScriptablePack source (`*.pack.ts`)
 
 Use `@forgeax/engine-pack/source` when one trusted TypeScript source declares
 and builds a multi-asset package. The definition owns one stable `packageId`;
@@ -260,7 +266,7 @@ vectors, colors, and asset-GUID constraints. The isolated Pack worker passes
 only serializable authoring data to the build and never exposes filesystem or
 runtime state.
 
-`forgeax-engine-remote-asset meta <source.pack.ts> --json` executes module initialization, validates the default export, and projects canonical Meta without calling `build`. `@forgeax/engine-pack/source-node` accepts a host executor with `load` and optional `dispose`; `timeoutMs` bounds module initialization and `buildTimeoutMs` bounds one `build(reader)` call. A build timeout returns one structured `pack-source-load-failed` Result with `detail.phase: 'build'`, the configured `timeoutMs`, and deterministic cleanup of the isolated worker and compile root.
+`forgeax-engine-remote-asset meta <source.pack.ts> --json` executes module initialization, validates the default export, and projects canonical Meta without calling `build`. `@forgeax/engine-pack/source-node` accepts a host executor with `load` and optional `dispose`; `timeoutMs` bounds module initialization and `buildTimeoutMs` bounds one `build(context)` call. A build timeout returns one structured `pack-source-load-failed` Result with `detail.phase: 'build'`, the configured `timeoutMs`, and deterministic cleanup of the isolated worker and compile root.
 
 The default worker executes the complete relative TypeScript module closure on the supported Node floor, including Node 22 hosts that do not load `.ts` files directly. It transpiles that closure into a disposable ESM directory, resolves bare imports through the source project's nearest `node_modules`, and removes the directory when the worker is disposed. Bulk producers use the internal `createScriptablePackModuleExecutorPool()` with two recyclable workers; a pooled lease is released after metadata projection or one build, so a generation never retains one live Worker-backed definition per source.
 
@@ -272,7 +278,7 @@ The default worker executes the complete relative TypeScript module closure on t
 > TypeScript remains inspectable and rebuildable, but unsupported structural
 > edits fail closed with stable `pack-source-*` errors.
 
-`SOURCE_AUTHORING_OPERATION_DESCRIPTORS` is the producer-owned structured capability manifest for tools. The existing `asset.preflight` operation returns the current revision, canonical Meta, incoming references, and shape-derived mutation capabilities before any write.
+`PACK_AUTHORING_OPERATION_DESCRIPTORS` is the producer-owned structured capability manifest for tools. The existing `asset.preflight` operation returns the current revision, canonical Meta, incoming references, and shape-derived mutation capabilities before any write.
 
 ```typescript
 import { AssetGuid } from "@forgeax/engine/pack/guid";

package/dist/__tests__/material-cook-receipt-layer-plan.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=material-cook-receipt-layer-plan.unit.test.d.ts.map

package/dist/__tests__/material-cook-receipt-layer-plan.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"material-cook-receipt-layer-plan.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/material-cook-receipt-layer-plan.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/pack-authoring-gateway.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pack-authoring-gateway.unit.test.d.ts.map

package/dist/__tests__/pack-authoring-gateway.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-authoring-gateway.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/pack-authoring-gateway.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/pack-authoring.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pack-authoring.unit.test.d.ts.map

package/dist/__tests__/pack-authoring.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-authoring.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/pack-authoring.unit.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/pack-scanner.unit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pack-scanner.unit.test.d.ts.map

package/dist/__tests__/pack-scanner.unit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-scanner.unit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/pack-scanner.unit.test.ts"],"names":[],"mappings":""}

package/dist/build.d.ts

@@ -11,14 +11,14 @@ export { projectAssetRefs, projectSceneEntityRefs } from './inventory/binding.js
 export { type AuthorInventory, type AuthorInventoryRow, type InventoryError, type InventoryErrorCode, validateAuthorInventory, } from './inventory/declaration.js';
 export { inventoryDigest, syncAuthorInventory } from './inventory/sync.js';
 export { decodeMeshBinHeader, MESH_BIN_DIGEST_BYTES, MESH_BIN_HEADER_V4_BYTES, MESH_BIN_PROJECTION_VERSION, MESH_BIN_VERSION, type MeshBinContractError, type MeshBinHeaderResult, type MeshBinHeaderV4, writeMeshBinHeader, } from './mesh-bin-contract.js';
+export * from './pack-authoring.js';
+export { createFileSystemPackAuthoringGateway, createFileSystemPackAuthoringPort, type FileSystemPackAuthoringOptions, type PackAuthoringMaterializedAsset, } from './pack-authoring-node.js';
 export { type FinalizedPackageProduct, finalizePackageProduct, finalizePackageTransportSource, type PackageArtifactBody, type PackageFinalizePolicy, type PackageFinalizeResult, type PackageFinalizerError, type PackageProduct, type PackageProductAsset, packageTransportRevision, } from './package-finalizer.js';
-export * from './parameterized-pack.js';
-export { createFileSystemParameterizedPackAuthoringGateway, createFileSystemParameterizedPackAuthoringPort, type FileSystemParameterizedPackAuthoringOptions, type ParameterizedPackMaterializedAsset, } from './parameterized-pack-node.js';
 export { validateProducerContract, validateProducerOutputs } from './producer-contract.js';
 export { resolveAssetSource } from './resolve-asset-source.js';
 export { parsePackV2, validateMeta, validatePack, validatePackV2 } from './runtime.js';
 export { createRuntimePackPublication, type RuntimePackAssetInput, type RuntimePackEnvelope, type RuntimePackInput, type RuntimePackPublication, type RuntimePackPublicationInput, } from './runtime-publication.js';
-export { type InventoryDeclaration, type LegacyPackInventoryDocument, type PackInventoryAsset, type PackInventoryDocument, type ParameterizedPackInventoryDocument, type ScanInventory, type ScanOptions, type ScanSourceDeclaration, type ScriptablePackInventoryDeclaration, type ScriptablePackScanOptions, STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS, scanInventory, } from './scanner.js';
+export { type InventoryDeclaration, type LegacyPackInventoryDocument, type PackInventoryAsset, type PackInventoryDocument, type PackSourceInventoryDocument, type ScanInventory, type ScanOptions, type ScanSourceDeclaration, type ScriptablePackInventoryDeclaration, type ScriptablePackScanOptions, STANDARD_SCRIPTABLE_PACK_SCAN_OPTIONS, scanInventory, } from './scanner.js';
 export { type AssetReader, isScriptablePackAssetKind, projectScriptablePackSceneComponents, SCRIPTABLE_PACK_ASSET_KINDS, type ScriptablePackAssetKind, type ScriptablePackReadError, type ScriptablePackSourceClosureEntry, } from './scriptable-pack.js';
 export { calculateTopologyDiff, diffTopology } from './topology.js';
 //# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,aAAa,EACb,cAAc,EACd,KAAK,EACL,cAAc,EACd,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,aAAa,EACb,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,oBAAoB,EACpB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,6BAA6B,EAC7B,qBAAqB,EACrB,wBAAwB,EACxB,KAAK,sBAAsB,GAC5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,oBAAoB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,KAAK,oBAAoB,EACzB,KAAK,+BAA+B,EACpC,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,2BAA2B,EAC3B,6BAA6B,EAC7B,4BAA4B,EAC5B,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAChG,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC3B,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,KAAK,uBAAuB,EAC5B,sBAAsB,EACtB,8BAA8B,EAC9B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EACL,iDAAiD,EACjD,8CAA8C,EAC9C,KAAK,2CAA2C,EAChD,KAAK,kCAAkC,GACxC,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EACL,4BAA4B,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,GACjC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,kCAAkC,EACvC,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,kCAAkC,EACvC,KAAK,yBAAyB,EAC9B,qCAAqC,EACrC,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,WAAW,EAChB,yBAAyB,EACzB,oCAAoC,EACpC,2BAA2B,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,GACtC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAGA,YAAY,EACV,aAAa,EACb,cAAc,EACd,KAAK,EACL,cAAc,EACd,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,MAAM,EACN,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,aAAa,EACb,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,UAAU,GACX,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,yBAAyB,EAC9B,oBAAoB,EACpB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,oBAAoB,EACpB,oBAAoB,EACpB,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,yBAAyB,EACzB,6BAA6B,EAC7B,qBAAqB,EACrB,wBAAwB,EACxB,KAAK,sBAAsB,GAC5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,KAAK,oBAAoB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,KAAK,oBAAoB,EACzB,KAAK,+BAA+B,EACpC,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,2BAA2B,EAC3B,6BAA6B,EAC7B,4BAA4B,EAC5B,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAChG,OAAO,EACL,SAAS,EACT,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,uBAAuB,GACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC3B,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,kBAAkB,GACnB,MAAM,wBAAwB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EACL,oCAAoC,EACpC,iCAAiC,EACjC,KAAK,8BAA8B,EACnC,KAAK,8BAA8B,GACpC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,uBAAuB,EAC5B,sBAAsB,EACtB,8BAA8B,EAC9B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,wBAAwB,GACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACvF,OAAO,EACL,4BAA4B,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,2BAA2B,GACjC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,oBAAoB,EACzB,KAAK,2BAA2B,EAChC,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,kCAAkC,EACvC,KAAK,yBAAyB,EAC9B,qCAAqC,EACrC,aAAa,GACd,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,WAAW,EAChB,yBAAyB,EACzB,oCAAoC,EACpC,2BAA2B,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,uBAAuB,EAC5B,KAAK,gCAAgC,GACtC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}