@forgeax/engine-import 0.1.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,226 @@
+# @forgeax/engine-import
+
+## Authoring and recovery index
+
+ScriptablePack sources use the public `@forgeax/engine-import` producer bridge.
+The output is the same Pack v2 durable payload used by ordinary importers. The
+16 `SCRIPTABLE_PACK_ASSET_KINDS` are `mesh`, `material`, `scene`, `texture`,
+`equirect`, `sampler`, `font`, `render-pipeline`, `tileset`, `video`,
+`skeleton`, `skin`, `animation-clip`, `animation-graph`, `audio`, and
+`particle-effect`; all are loadable by GUID, while `refs`,
+`artifacts`, `mediaType`, and `programFingerprint` remain producer facts.
+Producer or dependency failures return `code`, `expected`, `hint`, and
+`detail`; inspect the owning evidence, rebuild or cold-cook, and retry.
+
+The import contract is [`asset-authority.schema.json`](../../asset-authority.schema.json). `ImporterRegistry` and `runImport` are the build-time owner for external source plus Meta; every writable multi-output declaration uses a stable `sourceKey`, while `sourceIndex` remains diagnostic evidence only.
+
+| Need | Entry | Boundary |
+|:--|:--|:--|
+| Inspect producer evidence | Pack CLI `lookup` and `verify` JSON output | Read Catalog and receipt facts; do not parse messages |
+| Rebuild | Registered importer through `runImport` | Write Pack/DDC output through the shared finalizer |
+| Recover failed output | Fix source or Meta, then cold cook | Never return raw source as a runtime projection |
+| Preview old output | Explicit Catalog last-known-good locator | Read-only preview; not current and not publishable |
+
+The Importer owns neither DDC lifecycle nor Editor authoring writes. Editor writes go through its asset-authoring gateway, and runtime consumes the validated projection.
+
+Build-time asset **import** runner + `ImporterRegistry` — the build-time half of
+the engine's import/load split.
+
+> [!IMPORTANT]
+> **Build-time only.** This package never enters the player runtime bundle
+> (AC-06). `@forgeax/engine-runtime` and `@forgeax/engine-app` do not depend on
+> it. Its consumers are build tooling (the Vite pack plugin, the asset CLI).
+
+## The DIP (dependency-inversion principle) shape
+
+This is the engine's **third DIP instance** after RHI and Console. The engine
+owns the contract (`Importer` / `ImportContext` / `ImportTransport` in
+`@forgeax/engine-types`); concrete importers are injected by the host.
+
+```ts
+// Host assembly (vite.config.ts or build script)
+import { pluginPack } from '@forgeax/engine-vite-plugin-pack';
+import { gltfImporter } from '@forgeax/engine-gltf';
+import { imageImporter } from '@forgeax/engine-image/image-importer';
+
+export default {
+  plugins: [
+    pluginPack({
+      importers: [gltfImporter, imageImporter],
+    }),
+  ],
+};
+```
+
+### Three iron laws (architecture invariants)
+
+1. **GUID import-stable**. The `*.meta.json` sidecar pins every target GUID at
+   declare time. Import only reproduces those GUIDs, never mints new ones.
+2. **Lazy**. The runtime reads meta only to build a *catalog* (which GUIDs
+   exist, with which `kind`). Only a real `AssetRegistry.load(guid, kind)` triggers import
+   (when the DDC is absent) + load. No eager full-import on startup.
+3. **One-way dependency**. The engine owns the `Importer` interface; concrete
+   importers are injected. The engine never reverse-imports `gltfImporter` /
+   `imageImporter` / etc.
+
+## The import/load split
+
+```mermaid
+flowchart LR
+  src["source\n(.gltf / .png / .ttf)"] -->|"importer.import(ctx)"| ia["ImportedAsset[]\n(Asset PODs + GUIDs)"]
+  meta["*.meta.json\nimporter + subAssets[].guid"] --> ia
+  ia -->|"import runner\n(GUID iron law)"| ddc["DDC\n.pack.json / .bin"]
+  ddc -->|"AssetRegistry.load(guid, kind)"| runtime["runtime Loader\n(@forgeax/engine-assets-runtime)"]
+```
+
+- An **`Importer`** (`{ key, import }`) turns one external source + its
+  `*.meta.json` GUID declarations into in-memory `ImportedAsset[]` PODs. It is
+  pure of disk write + GUID minting — it reads the GUIDs declared in the meta
+  (the **GUID import-stable iron law**) and stamps them onto the PODs.
+- The **import runner** (`runImport(meta, registry, fs)`) dispatches a sidecar
+  by its top-level `importer` string key to the registered `Importer`,
+  validates the produced GUID set against the declared set, and folds the
+  result into a DDC `.pack.json` document. The reserved key **`importer:
+  'shader'`** is skipped — shader sidecars are consumed by
+  `@forgeax/engine-vite-plugin-shader`'s orthogonal transform pipeline.
+- **`ImportTransport`** (interface in `@forgeax/engine-types`) bridges the
+  build-time importer to the runtime: the shipped form wires `null` transport
+  (pre-import at build time, DDC miss -> fail-fast `asset-not-imported`); the
+  studio form wires an HTTP adapter (`POST /__import/:guid`) for lazy on-demand
+  import.
+
+## Injection shape
+
+### ScriptablePack build bridge
+
+`buildScriptablePack` decorates a host-provided Asset snapshot source with the ordinary `AssetReader`. Each GUID is fixed to one generation/digest and cloned for the current Build. The adapter validates the exact output-key/kind closure, stamps descriptor identity, dispatches each Asset to the reusable `AssetOutputProducerRegistry`, and derives external usage from actual reads plus serialized refs.
+
+| Derived usage | Input fingerprint | Runtime ref |
+|:--|:--|:--|
+| `content` | Asset generation and digest | No |
+| `reference` | GUID only | Yes |
+| `both` | Asset generation and digest | Yes |
+
+Domain producers return structured `ImportError`; the generic bridge contains no per-kind switch. `createStandardAssetOutputProducerRegistry()` composes the production Scene, Material, and Mesh owners. Scene refs use the ECS externalization kernel shared with runtime save, Material refs cover parent/texture/sampler GUIDs, and Mesh emits the versioned binary artifact. The fingerprint covers canonical Meta, the recursive source closure, observed external evidence, authoring contract version, and registered producer versions.
+
+`createScriptablePackStagedAssetSnapshotSource()` owns clean-build content reads. It resolves a GUID to its local source owner, lazily builds that owner inside one fixed generation, memoizes private clones and digests, and reports `pack-source-build-cycle` without consulting an older fallback generation. A fallback is only an explicit prebuilt authority for GUIDs with no local owner.
+
+`createStandardAssetOutputProducerRegistry()` registers the production
+Material, Mesh, and Scene producers. Material output derives
+parent/texture/sampler refs; Mesh output derives default-material refs and emits
+the `mesh-binary/4` body; Scene output uses the shared ECS externalization
+contract. A specialized host may instead register only the admitted kinds:
+
+```ts
+const outputs = new AssetOutputProducerRegistry();
+outputs.register(materialAssetOutputProducer);
+outputs.register(meshAssetOutputProducer);
+```
+
+### Mesh binary v4 producer contract
+
+The Mesh producer calls [`packMeshBinV4`](src/mesh-bin.ts), which delegates
+projection facts to geometry and records one stable digest, mask, stride,
+cardinality, and payload length in the artifact header. Material defaults are
+references into the producer refs table; GUID strings are not duplicated in the
+binary metadata.
+
+> [!IMPORTANT]
+> A producer Result error contains `subject`, `sourceKey`, `expected`,
+> `actual`, and a re-cook recovery hint. Failed validation returns no artifact,
+> so the importer cannot publish a partial mesh product. v2/v3 mesh binaries
+> are not compatibility inputs.
+
+At the low-level `buildScriptablePack` boundary, `assetSource` is optional only
+when `build` never calls `reader.readByGuid`. The first attempted content read
+without a source returns structured `asset-not-found`; no empty snapshot or
+stale content is invented. Production Vite hosts provide the staged generation
+source described above.
+
+`ImporterRegistry` mirrors the runtime `LoaderRegistry` and the Console
+`Registry`: `register(importer)` (fail-fast on a malformed importer, idempotent
+on a repeated key) + `get(key)` (returns `undefined`, which the runner maps to a
+structured `ImportError(code='importer-not-registered')`).
+
+```ts
+import { ImporterRegistry, runImport } from '@forgeax/engine-import';
+import { readFile } from 'node:fs/promises';
+
+const registry = new ImporterRegistry();
+registry.register(gltfImporter);
+
+const fs = {
+  async readSource(path: string) {
+    try {
+      const buf = await readFile(path);
+      return { ok: true, value: new Uint8Array(buf) };
+    } catch (e) {
+      return { ok: false, error: e };
+    }
+  },
+};
+
+const result = await runImport(
+  { importer: 'gltf', source: 'assets/box.gltf', subAssets: [...] },
+  registry,
+  fs,
+);
+if (result.ok) {
+  console.log('DDC .pack.json:', result.value.pack);
+}
+```
+
+## Error model
+
+`ImportErrorCode` is a closed 5-member union (exhaustive `switch (err.code)`,
+no `default:`). `ImportError` carries the four-field structured surface
+(`.code` / `.expected` / `.hint` / `.detail`); SSOT lives in
+`@forgeax/engine-types`.
+
+| code | trigger |
+|:--|:--|
+| `importer-not-registered` | `meta.importer` has no registered importer |
+| `source-read-failed` | `meta.source` could not be read |
+| `import-produced-no-assets` | importer produced nothing, or omitted a declared GUID |
+| `guid-mismatch` | importer produced a GUID not declared in `meta.subAssets[]` |
+| `import-internal-error` | importer conversion or finalization failed; the runner wraps it in the existing structured Result. Finalization/digest failures carry a `detail.reason` prefixed with `finalization/digest`, and no CookProduct or Pack is returned for the failed attempt |
+
+## Dual-form transport (M4)
+
+| Form | `ImportTransport` | DDC source | DDC miss behavior |
+|:--|:--|:--|:--|
+| **studio** (dev server) | HTTP adapter `POST /__import/:guid` | lazily imported on demand | `transport.fetchPack(guid)` -> import -> load |
+| **shipped** (player bundle) | `undefined` (null transport) | build-time pre-import via `generateBundle` | `asset-not-imported` fail-fast (never downgrades to runtime import) |
+
+The runtime load path is **identical** in both forms — `ddcLoad` has zero
+branches on transport. The only difference is whether `transportOrFail` is
+reached on DDC miss (studio: it calls the transport; shipped: it returns the
+error immediately).
+
+## Indexed source-package lifecycle
+
+Use this sequence when an import or Pack consumer reports a missing product:
+
+1. **Inspect** the source Meta, declared GUID closure, Catalog row, DDC head,
+   and producer receipt. Read the closed error union's `code` and `detail`.
+2. **Repair** the source, Meta, or registered importer named by the detail.
+   `ImporterRegistry` owns dispatch, while the source plus Meta remains the
+   author authority.
+3. **Rebuild** when the existing DDC entry can be replaced safely; **cold-cook**
+   when integrity, receipt, or lifecycle state says the derived entry is
+   invalid. Both paths use `runImport` and the shared finalizer.
+4. **Verify** GUID closure, receipt freshness, DDC integrity, Pack artifacts,
+   and the projected Catalog row.
+5. **Retry** the same GUID after verification. Never parse an error message or
+   turn an unverified source file into a runtime payload.
+
+`runImport` keeps conversion and finalization failures inside its structured
+Result boundary. A digest-capability refusal during CookProduct finalization
+does not publish a partial product; repair that capability and retry the same
+Meta/GUID through the same `ImporterRegistry`.
+
+The import package stops at build-time source conversion and product
+publication. It does not write authoring state, own Editor operations, or add
+runtime transport branches. A dev `ImportTransport` is an explicit host
+adapter; a shipped bundle must carry its build-time product and keeps
+`asset-not-imported` fail-fast semantics.