space-data-module-sdk 0.5.21 → 0.5.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.5.21",
+  "version": "0.5.22",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
   "types": "./src/index.d.ts",

package/src/AGENTS.md

@@ -1,9 +1,9 @@
 # AGENTS
 
-Apply the root `AGENTS.md` first. This file routes source edits to the correct
-subsystem.
+Apply the root `AGENTS.md` first. This file is a map for module authors reading
+the SDK source, not a prompt to edit SDK internals by default.
 
-## Source Routing
+## Use `src/` As A Reference Map
 
 - `src/manifest`, `src/compliance`, `src/standards`: manifest shape, type refs,
   standards validation, and compliance warnings/errors.
@@ -23,11 +23,10 @@ subsystem.
 - `src/generated`: generated code. Do not hand-edit unless regeneration is part
   of the task and you update the generation path or fixtures as needed.
 
-## Working Rules
+## Author Rules
 
-- Keep module contracts portable unless the task is explicitly runtime-specific.
-- Prefer changes in the smallest subsystem that owns the behavior.
-- If a change crosses compiler, host, and docs, update each owner explicitly
-  rather than hiding policy in one layer.
-- Add or update tests near the owning subsystem and then wire them into the
-  repo-level verification set in `test/AGENTS.md`.
+- Prefer public APIs and examples over editing `src/*`.
+- Read the nearest child `AGENTS.md` to understand which source files define the
+  contract you are using.
+- Only edit internals here when the task explicitly says to change the SDK
+  standard for everyone.

package/src/auth/AGENTS.md

@@ -1,15 +1,13 @@
 # AGENTS
 
-You are in `src/auth`, which owns deployment authorization, signing helpers,
-and related record handling used by module distribution.
+This directory is the reference implementation for deployment authorization and
+signing helpers used by compliant module distribution.
 
-## Rules
+## What Authors Should Use It For
 
 - Keep signing and authorization flows deterministic and explicit.
 - Do not invent app-local signature records when a repo-level contract belongs
   here.
-- When auth changes affect transport or deployment plans, update the related
-  surfaces together rather than splitting incompatible changes across repos.
 
 ## Related Surfaces
 
@@ -18,8 +16,7 @@ and related record handling used by module distribution.
 - `test/transport-records.test.js`
 - `test/deployment-plan.test.js`
 
-## Check Before You Finish
+## Note
 
-- `npm test`
-- `npm run check:compliance`
-- `node --test test/transport-records.test.js test/deployment-plan.test.js`
+Use the exported helpers here rather than inventing your own signing records.
+Only edit this directory when you are intentionally changing the auth contract.

package/src/bundle/AGENTS.md

@@ -1,21 +1,17 @@
 # AGENTS
 
-You are in `src/bundle`, which owns `sds.bundle` and the wasm custom-section
-packaging rules.
+This directory is the reference implementation for `sds.bundle` and wasm
+custom-section packaging.
 
-## Rules
+## What Authors Should Use It For
 
 - `sds.bundle` is the single-file delivery format.
 - Put bundle data in a wasm custom section; do not append raw bytes after the
   wasm binary.
-- Keep parser, encoder, CLI behavior, vectors, and cross-language fixtures in
-  sync.
-- If the bundle contract changes, regenerate vectors and update the bundle docs
-  and demos in the same change.
+- Use the public bundle helpers and CLI from this repo rather than inventing a
+  custom one-file format.
 
-## Check Before You Finish
+## Note
 
-- `npm test`
-- `npm run check:compliance`
-- `node --test test/module-bundle.test.js test/module-bundle-vectors.test.js test/module-bundle-cli.test.js test/module-bundle-go.test.js test/module-bundle-python.test.js`
-- `npm run generate:vectors` when vectors or the contract changed
+Only edit this directory when you are intentionally changing bundle behavior for
+all consumers.

package/src/compiler/AGENTS.md

@@ -1,13 +1,18 @@
 # AGENTS
 
-Apply the root and `src/AGENTS.md` files first.
+Apply the root and `src/AGENTS.md` files first. This directory tells module
+authors how the compiler behaves.
 
-## Area Ownership
+## What Authors Should Take From This Directory
 
-This directory owns source-to-wasm compile behavior, manifest embedding, runtime
-target inference, toolchain integration, and canonical artifact layout.
+- `compileModuleFromSource(...)` and the CLI are the canonical ways to produce a
+  compliant artifact.
+- Manifest embedding and required exports are generated together with the wasm
+  bytes.
+- Shared browser/WasmEdge artifacts should land at
+  `dist/isomorphic/module.wasm`.
 
-## Compiler Rules
+## Compiler Rules Authors Should Follow
 
 - Preserve the canonical manifest accessor exports and validate them together
   with compiled wasm.
@@ -18,18 +23,15 @@ target inference, toolchain integration, and canonical artifact layout.
   imports.
 - Prefer repo-local Emscripten or `sdn-emception`. Do not assume Homebrew
   toolchains.
-- If you change runtime-target inference, keep the browser/WasmEdge shared path
-  on the standalone profile unless the docs and tests are updated deliberately.
 
-## Key Files
+## Key Files To Read
 
 - `compileModule.js`
 - `compileModuleFromSource.js`
 - `emception*.js`
 - `invokeGlue.js`
 
-## Verification
+## Note
 
-- `node --test test/module-sdk.test.js test/compliance.test.js`
-- `node --test test/browser-harness.test.js test/isomorphic-loader.test.js`
-- `node --test test/compiler-emception-subpath-export.test.js`
+Do not edit compiler internals just to build one module. Only change this
+directory when you are intentionally changing the repo-wide compile contract.

package/src/compliance/AGENTS.md

@@ -1,18 +1,16 @@
 # AGENTS
 
-You are in `src/compliance`, which defines what counts as a compliant module or
+This directory is the reference policy for what counts as a compliant module or
 artifact.
 
-## Rules
+## What Authors Should Use It For
 
-- Treat this directory as policy, not convenience code.
-- When tightening validation, update tests and error messages together so the
-  failure mode is actionable.
-- When relaxing validation, make sure the compiler, docs, and examples still
-  describe the broader contract accurately.
+- Use the CLI and public validation helpers to understand whether a manifest or
+  artifact is compliant.
+- Read this directory when you need to know why a module was rejected.
+- Prefer fixing your module manifest or build output before changing policy here.
 
-## Check Before You Finish
+## Note
 
-- `npm test`
-- `npm run check:compliance`
-- `node --test test/module-sdk.test.js test/compliance.test.js`
+Only edit this directory when you are intentionally changing the compliance
+standard for all module authors.

package/src/host/AGENTS.md

@@ -1,14 +1,17 @@
 # AGENTS
 
-Apply the root and `src/AGENTS.md` files first.
+Apply the root and `src/AGENTS.md` files first. This directory explains the
+host/runtime boundary that compliant modules can rely on.
 
-## Area Ownership
+## What Authors Should Take From This Directory
 
-This directory owns the Node reference host, browser host, browser edge shims,
-WASI shims, the sync `sdn_host` ABI bridge, WasmEdge launch planning, and the
-isomorphic loader path.
+- The portable shared path is standalone WASI, optionally plus `sdn_host`.
+- Browser helpers here are host-side shims and harnesses, not proof that raw
+  WasmEdge-native guest imports are browser-portable.
+- The isomorphic loader and browser harness show how the same artifact is meant
+  to run in both places.
 
-## Host Rules
+## Host Rules Authors Should Follow
 
 - Shared browser/WasmEdge artifacts must stay within standalone WASI plus the
   optional `sdn_host` bridge. Raw WasmEdge-native extension imports are not
@@ -20,7 +23,7 @@ isomorphic loader path.
 - Scope host capabilities tightly: filesystem roots, network allowlists, TLS,
   exec, timers, and crypto should stay explicit.
 
-## Key Files
+## Key Files To Read
 
 - `abi.js`
 - `browserEdgeShims.js`
@@ -29,11 +32,7 @@ isomorphic loader path.
 - `nodeHost.js`
 - `wasiShim.js`
 
-## Verification
+## Note
 
-- `node --test test/node-host.test.js test/host-abi.test.js`
-- `node --test test/browser-harness.test.js test/isomorphic-loader.test.js`
-- `node --test test/process-invoke.test.js`
-- `node --test test/wasmedge-runner-build.test.js`
-- `node --test test/wasmedge-runner-runtime.test.js` when WasmEdge behavior is
-  part of the change
+Prefer using the exported host and harness surfaces rather than editing these
+files unless the task is explicitly to change the SDK host contract.

package/src/manifest/AGENTS.md

@@ -1,18 +1,15 @@
 # AGENTS
 
-You are in `src/manifest`, which owns the manifest schema codecs and
-normalization rules.
+This directory is the reference implementation for manifest encoding,
+normalization, and round-trip behavior.
 
-## Rules
+## What Authors Should Use It For
 
 - Keep manifest encode/decode round-trips stable.
 - Prefer canonical SDS schema names and file identifiers; do not add repo-local
   aliases when a standards name already exists.
-- If you change a manifest field or normalization rule, update the compiler,
-  compliance checks, and any affected examples/tests together.
 
-## Check Before You Finish
+## Note
 
-- `npm test`
-- `npm run check:compliance`
-- `node --test test/module-sdk.test.js test/compliance.test.js`
+Use the public manifest helpers from this repo to build manifests. Only edit
+this directory when you are intentionally changing the manifest standard.

package/src/runtime-host/AGENTS.md

@@ -1,12 +1,15 @@
 # AGENTS
 
-Apply the root and `src/AGENTS.md` files first.
+Apply the root and `src/AGENTS.md` files first. This directory shows the
+host-owned storage and ingest path available to module authors.
 
-## Area Ownership
+## What Authors Should Take From This Directory
 
-This directory owns the canonical runtime-host storage model: row handles,
-region handles, FlatSQL-backed storage, and binary FlatBuffer ingest on the host
-side.
+- Host-owned durable identity is `(schemaFileId, rowId)` for rows and
+  `(regionId, recordIndex)` for aligned-binary regions.
+- The canonical ingest path is direct FlatBuffer bytes, not JSON.
+- If the host owns persistence, use these helpers. If a module owns state, keep
+  the stream binary and use the resident-module pump path from `src/testing`.
 
 ## Storage And Streaming Rules
 
@@ -19,14 +22,13 @@ side.
 - If a resident module owns state, keep the stream binary and push into the
   module through the harness/pump path rather than inventing JSON wrappers.
 
-## Key Files
+## Key Files To Read
 
 - `flatbufferStreamIngestor.js`
 - `flatsqlRuntimeStore.js`
 - `index.js`
 
-## Verification
+## Note
 
-- `npm run test:stream-ingest`
-- `node --test test/flatsql-local-node.test.js`
-- `npm run benchmark:stream-1gib` for large-stream changes
+Do not edit this directory just to store data for one module. Use the exported
+helpers unless you are intentionally changing the runtime-host contract.

package/src/testing/AGENTS.md

@@ -1,12 +1,15 @@
 # AGENTS
 
-Apply the root and `src/AGENTS.md` files first.
+Apply the root and `src/AGENTS.md` files first. This directory contains the
+author-facing harnesses and streaming helpers.
 
-## Area Ownership
+## What Authors Should Use From Here
 
-This directory owns SDK test harnesses and runtime-facing helper surfaces used
-by examples and downstream consumers: browser harnesses, generic process invoke
-clients, runtime-matrix helpers, and resident-module FlatBuffer pumps.
+- `createBrowserModuleHarness(...)` is the browser-side proof path for shared
+  standalone artifacts.
+- `createModuleHarness(...)` is the generic process-side harness.
+- `createModuleFlatBufferStreamPump(...)` is the canonical no-JSON path for
+  streaming size-prefixed FlatBuffer frames into a resident module instance.
 
 ## Harness Rules
 
@@ -19,15 +22,13 @@ clients, runtime-matrix helpers, and resident-module FlatBuffer pumps.
 - Avoid hiding stateful behavior inside one-off demos; if a harness contract is
   real, test it here.
 
-## Key Files
+## Key Files To Read
 
 - `browserModuleHarness.js`
 - `moduleFlatbufferStreamPump.js`
 - `processInvoke.js`
 
-## Verification
+## Note
 
-- `node --test test/browser-harness.test.js`
-- `node --test test/isomorphic-loader.test.js`
-- `npm run test:module-stream`
-- `node --test test/process-invoke.test.js`
+Use these helpers from your module repo or app harnesses. Only edit them when
+you are intentionally changing the SDK testing/runtime contract.