@forgeax/game 0.3.2 → 0.3.4

package/docs/asset3d.md

@@ -14,11 +14,13 @@ second importer or Preview server.
 
 > [!IMPORTANT]
 > Provider archives are platform-specific artifacts. The npm package embeds the
-> currently released Darwin arm64 archive so a cache-empty user does not depend on a
-> private source repository or release download. Installation deliberately returns
+> currently released Darwin arm64 and Linux x64 archives so a cache-empty user does
+> not depend on a private source repository or release download. Linux requires an
+> x86-64 host and Python 3.11 or 3.12. Installation deliberately returns
 > `provider_platform_mismatch` when an archive target differs from the current host.
-> Each bundled target therefore needs its own digest, offline verification, MCP
-> handshake, and real service-path evidence.
+> Unsupported targets such as Linux arm64 and Windows fail closed. Each bundled
+> target therefore needs its own digest, offline verification, MCP handshake, and
+> real service-path evidence.
 
 ## Trust and data flow
 
@@ -54,19 +56,22 @@ one-to-eight member set is sorted and encoded as compact JSON in
 digest. The provider is responsible for enforcing that set on both initial and
 redirect requests.
 
-Normal installation writes the normalized AW service root to `AW_API_BASE_URL` and an
-absolute user credential-file path to `AW_API_CREDENTIAL_FILE`. It never writes
-`AW_API_SANDBOX_KEY` into project MCP configuration. `--catalog-base-url` remains a
+Normal installation writes the selected service root to `AW_API_BASE_URL`, the
+matching `AW_API_DEPOT_NAME=aw|ea`, and an absolute user credential-file path to
+`AW_API_CREDENTIAL_FILE`. The `AW_API_*` names are the packaged Provider's legacy
+environment contract. Installation never writes `AW_API_SANDBOX_KEY` into project
+MCP configuration. `--catalog-base-url` remains a
 maintainer-only compatibility adapter for the retired directory service; when used,
 its authority must also appear in `--download-origin`.
 
 ## Installation ownership
 
-`asset3d enable` uses the documented AW production service when no override is
-present. Service selection precedence is explicit `--base-url`, then
-`FORGEAX_ASSET_LIBRARY_BASE_URL`, then the built-in production service. Therefore a
-test environment is contacted only when the caller supplies its gateway or service
-URL. The first interactive run asks for the AW Sandbox Key with terminal echo
+`asset3d enable` keeps the public AW depot by default. `--library ea` selects the EA
+depot and its office-network local gateway; `FORGEAX_ASSET_LIBRARY=ea` is the
+deployment equivalent. Gateway selection precedence is explicit `--base-url`, then
+`FORGEAX_ASSET_LIBRARY_BASE_URL`, then the selected library's built-in service.
+Gateway overrides never change the selected depot. The first interactive run asks
+for the Sandbox Key with terminal echo
 disabled. Automation can supply `FORGEAX_ASSET3D_AW_SANDBOX_KEY` from a secret store;
 command-line key arguments are deliberately unsupported.
 
@@ -109,6 +114,13 @@ idempotent. Uninstall removes only entries and Skill files that still match owne
 digests, leaving user-modified or unrelated content in place and reporting the
 collision.
 
+For user-scoped MCP hosts such as Codex, Cursor, and Claude, `enable` additionally
+registers a non-secret `asset3d-search` bridge command. The bridge resolves
+`.forgeax/asset3d-install.json` and the owned `.forgeax/mcp.json` entry from the host
+process working directory, rather than pinning a user config to one project. A
+project without an Asset3D installation receives a healthy MCP handshake with an
+empty tool list. Start a new Agent session after enabling so `search_asset` appears.
+
 The workflow package is projected beneath `art-3d-asset-library/` in exactly these
 mounts unless `--ide` selects a subset:
 
@@ -127,19 +139,22 @@ has its path, byte count, and digest in the ownership manifest.
 
 1. `asset3d begin` records a private journal with a new execution UUID, query digest,
    provider identity, exact Engine identity, requested count, and the only allowed
-   quarantine root. It returns the relative `output_dir` for `search_asset`; the
-   provider's `MCP_SHARED_PATH` is the same private `workspace/` root, so declared
-   manifest paths and transaction validation address identical bytes.
-2. The configured provider writes beneath that directory and returns one checked
-   `forgeax.asset3d-search-result/1.0.0` TextContent JSON object.
-3. `asset3d commit --provider-result-stdin` reads at most 1 MiB, validates exact
-   fields/counts/roles/digests/sorted relative paths, and ignores `downloaded_to`.
-4. The transaction rejects symlinks, special files, undeclared files, realpath escape,
+   quarantine root.
+2. `search_asset` accepts that execution UUID instead of an output path. The Game
+   Plugin bridge verifies the exact queries and injects the transaction-owned
+   provider directory beneath its private `workspace/` root.
+3. The configured provider writes beneath that directory and returns one checked
+   `forgeax.asset3d-search-result/1.0.0` TextContent JSON object. The bridge stores
+   those exact bytes against the execution; the agent does not copy the object.
+4. `asset3d commit --execution <uuid>` reads the stored result (at most 1 MiB),
+   validates exact fields/counts/roles/digests/sorted relative paths, and ignores
+   `downloaded_to`.
+5. The transaction rejects symlinks, special files, undeclared files, realpath escape,
    byte mismatch, or digest mismatch before a project asset write.
-5. A 30-second per-asset lock serializes publication at
+6. A 30-second per-asset lock serializes publication at
    `assets/3d/ea-3d/<safeAssetId>`. The complete prior directory is preserved as the
    refresh/rollback snapshot.
-6. With the game root as `cwd`, Game Plugin runs the exact released Engine CLI:
+7. With the game root as `cwd`, Game Plugin runs the exact released Engine CLI:
 
    ```text
    asset add assets/3d/ea-3d/<safeAssetId> --reimport-policy semantic-only --json
@@ -151,7 +166,7 @@ has its path, byte count, and digest in the ownership manifest.
    Each command must produce exactly one newline-terminated, at-most-1-MiB
    `CommandEnvelope@1.0.0`. Game Plugin does not filter diagnostic stdout into a
    synthetic success.
-7. Only after Engine readback succeeds does `.forgeax-asset.json` publish the provider
+8. Only after Engine readback succeeds does `.forgeax-asset.json` publish the provider
    commit, origin-set digest, exact Engine version/commit, per-file role/digest/bytes,
    Engine rows, and catalog readback. An Engine failure restores the whole previous
    asset directory.
@@ -165,11 +180,12 @@ successful; `asset3d abort` removes only its transaction quarantine.
 ## Distribution and evidence boundary
 
 The packed Game Plugin includes the self-contained CLI bundle, existing connector
-Skill, exact K0 TGZ, checked P0 result/receipt schemas, and the immutable URL/digest
-table for supported Provider targets. It does not embed the Provider runtime archive,
-Engine payload, source checkout, credentials, or workspace links. Provider archives
-are separate release assets so a disabled installation downloads nothing. The package
-artifact gate recomputes every embedded predecessor digest.
+Skill, exact K0 TGZ, checked P0 result/receipt schemas, and an inert, digest-pinned
+Provider archive for every supported target. It does not embed a provisioned Python
+environment, managed Provider cache, Engine payload, source checkout, credentials, or
+workspace links. A disabled installation neither extracts an archive nor contacts a
+network service. The package artifact gate recomputes every embedded predecessor
+digest.
 
 Controlled external-consumer evidence may establish package installation, raw MCP
 framing, local redirect/ZIP handling, multi-GLB and texture import, reuse, refresh,

package/docs/release-0.3.3.md

@@ -0,0 +1,73 @@
+# `@forgeax/game` 0.3.3 release guide
+
+Version `0.3.3` adds the EA depot without removing the public AW path. The packaged
+provider is unchanged; one explicit library selection binds the matching depot and
+gateway together.
+
+> [!IMPORTANT]
+> EA is currently available only through the office-network `local` gateway.
+> There is no reachability-based fallback: silently changing libraries would make
+> identical queries resolve to different assets.
+
+## User contract
+
+```bash
+# Public/default
+npx -y @forgeax/game@0.3.3 asset3d enable
+
+# Office network
+npx -y @forgeax/game@0.3.3 asset3d enable --library ea
+
+npx -y @forgeax/game@0.3.3 asset3d doctor --json
+```
+
+The selected mode writes these non-secret provider settings:
+
+| Mode | Depot | Built-in gateway |
+|:--|:--|:--|
+| Default or `--library aw` | `aw` | Existing public AW service |
+| `--library ea` | `ea` | `http://test-ultrongw.woa.com/trpc.oasismetric.omcontentserver.http` |
+
+`FORGEAX_ASSET_LIBRARY=aw|ea` is the deployment selector. `--base-url` and
+`FORGEAX_ASSET_LIBRARY_BASE_URL` remain gateway overrides and never change the
+selected depot. The project stores only the service URL, depot name, private
+credential-file path, and live-derived download origins.
+
+## Transaction-bound search
+
+`search_asset` accepts the execution UUID returned by `asset3d begin`; it no longer
+accepts a caller-selected `output_dir`. The Game Plugin bridge verifies the execution
+and exact query list, then injects the private quarantine path before invoking the
+packaged provider. This removes agent path guesses such as `assets` from the tool
+contract while preserving the existing provider implementation.
+
+The bridge also persists the exact checked TextContent by execution. A normal commit
+is now `asset3d commit --execution <uuid> --json`; agents no longer reconstruct large
+provider JSON as shell input.
+
+`asset3d enable` now installs the generic `asset3d-search` bridge into every Agent
+host previously selected by `install`. The user-level launch command carries no key
+and no project path; it discovers the active project's owned Provider configuration
+from its working directory. Disabled projects advertise zero Asset3D tools. Start a
+new Agent session after enabling so the host refreshes its MCP tool inventory.
+
+## Verified migration
+
+- [x] EA access check succeeded through the packaged provider.
+- [x] Query `wooden barrel` returned EA asset `SM_Prop_Bucket_001.zip`.
+- [x] The provider downloaded and converted the result to GLB.
+- [x] Delivered result was 565,650 bytes with SHA-256
+  `17897a89e652170e7ab98b08dd71f10c4289e58b38caac52e0b41e44b5f72185`.
+- [x] The primary GLB was 314,908 bytes.
+- [ ] Registry publication and registry-downloaded tarball verification.
+
+## Release gates
+
+```bash
+bun run typecheck
+bun test test/*.test.ts
+FORGEAX_ASSET3D_PROVIDER_BUNDLE=<audited-provider-archive> bun run build
+FORGEAX_ASSET3D_PROVIDER_BUNDLE=<audited-provider-archive> \
+  npm pack --ignore-scripts --json --pack-destination <audited-directory>
+bun scripts/check-package-artifact.ts <audited-directory>/forgeax-game-0.3.3.tgz
+```

package/docs/release-0.3.4.md

@@ -0,0 +1,66 @@
+# @forgeax/game 0.3.4 release contract
+
+Version `0.3.4` adds a self-contained Linux x64 Asset3D Provider while preserving
+the existing opt-in workflow. Ordinary `install` and `init` remain platform-neutral
+and keep Asset3D disabled. A user enables Asset3D only from an initialized game:
+
+```bash
+npx -y @forgeax/game@0.3.4 asset3d enable
+npx -y @forgeax/game@0.3.4 asset3d doctor --json
+```
+
+## Supported Provider targets
+
+| Host | Provider archive SHA-256 | Status |
+|---|---|---|
+| Darwin arm64 | `9492c507a3afe5cafcd50b5f782b313c8716c2e52f5def06592c6a100c0459db` | Supported |
+| Linux x64 | `e6ac3df76c8b82f9fe2c063dd3f221324a9dad5176fd52535a5144b0ff6002d8` | Supported; Python 3.11 or 3.12 required |
+
+Both archives bind Provider commit
+`c181c48fbffc933a7ce9a0836f7878ca5e6d77e1`. The package build fails if either
+source archive is absent, is a symlink, or differs from its approved digest. The npm
+artifact gate repeats those checks against the packed bytes.
+
+The offline wheelhouses omit upstream dependency test suites and redact
+credential-shaped user-info from dependency documentation examples. Runtime modules
+and package metadata remain present, each rewritten wheel is re-RECORDed and
+hash-locked, and the resulting platform archives are byte-reproducible. This keeps
+test-only public tokens and false credential patterns out of the npm payload.
+
+Linux arm64 and Windows are not part of this release. `asset3d enable` fails closed
+with `asset3d_provider_target_unreleased` on those hosts; it does not install a
+different target or fall back to downloaded Provider code.
+
+## Linux release gate
+
+The Ubuntu x64 CI job performs the Linux-specific verification from the same package
+assets that are published:
+
+1. Provision the Provider into an empty managed cache without downloading Provider
+   code or Python dependencies.
+2. Verify the archive manifest, target, file digests, wheel lock, and converter.
+3. Execute the bundled Linux x64 `FBX2glTF` binary.
+4. Launch the installed Provider over stdio MCP and require `search_asset` in
+   `tools/list`.
+
+This proves Linux provisioning and MCP capability discovery. It does not substitute
+for an authenticated request to the internal AW service, which requires network
+reachability and user credentials and remains a separate environment acceptance
+gate.
+
+## Maintainer checklist
+
+- [ ] `bun run typecheck`
+- [ ] `bun test`
+- [ ] `bun run build`
+- [ ] `npm pack --ignore-scripts --pack-destination <empty-directory>`
+- [ ] `bun run release:check -- <exact-tarball>`
+- [ ] Ubuntu x64 `asset3d-linux-x64` CI job is green on the exact release commit.
+- [ ] The packed artifact contains both Provider archives and no credential, source
+      checkout, managed cache, or provisioned Python environment.
+- [ ] The exact tarball passes the repository secret and private-path scans before
+      publication.
+
+The AW production default and explicit EA override remain as documented in
+[`release-0.3.3.md`](release-0.3.3.md). Credential storage and real search/import
+acceptance boundaries remain unchanged and are defined in [`asset3d.md`](asset3d.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "bun@1.3.14",
   "name": "@forgeax/game",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "private": false,
   "type": "module",
   "description": "@forgeax/game — an MCP/CLI connector for exact released ForgeaX Engine games and Engine-owned Preview.",
@@ -24,6 +24,8 @@
     "docs/release-0.3.0.md",
     "docs/release-0.3.1.md",
     "docs/release-0.3.2.md",
+    "docs/release-0.3.3.md",
+    "docs/release-0.3.4.md",
     "README.md"
   ],
   "scripts": {
@@ -31,6 +33,7 @@
     "release:check": "bun scripts/check-package-artifact.ts",
     "acceptance": "bun scripts/accept-packed-consumer.ts",
     "acceptance:asset3d": "bun scripts/accept-asset3d-packed-consumer.ts",
+    "verify:asset3d-linux": "bun scripts/verify-linux-asset3d-provider.ts",
     "release:publish": "bun scripts/publish-package.ts",
     "prepack": "bun build.mjs",
     "typecheck": "tsc --noEmit",