@fortemi/core 2026.7.11 → 2026.7.13

package/README.md

@@ -123,8 +123,58 @@ const results = controller.query('deployment', {
 ```
 
 Use this subpath for Pagenary-style command palettes, static docs search, and
-vanilla JavaScript review surfaces. The top-level `@fortemi/core` export remains
-available for full archive/runtime integrations.
+vanilla JavaScript review surfaces. Its published `dist/aiwg-index.js` artifact
+is dependency-free, contains no import statements, and is kept below 50 KB so
+no-bundler consumers can vendor it verbatim.
+
+Knowledge Shard conversion intentionally lives on the build-oriented subpath:
+
+```ts
+import {
+  aiwgFortemiIndexFromKnowledgeShard,
+  aiwgFortemiIndexToKnowledgeShard,
+  aiwgFortemiIndexToKnowledgeShardWithReport,
+} from '@fortemi/core/aiwg-index-shard'
+```
+
+That subpath owns the schema, tar/gzip, checksum, and UUID dependencies. The
+top-level `@fortemi/core` export also remains available for full archive/runtime
+integrations.
+
+`aiwgFortemiIndexToKnowledgeShard` retains the reversible schema 1.2.0
+`core-v1` adapter. Native conversion uses the report-bearing entry point and
+the exact `2.0.0/full-v1` tuple:
+
+```ts
+const result = await aiwgFortemiIndexToKnowledgeShardWithReport(index)
+
+if (!result.success) {
+  console.table(result.losses)
+  throw new Error('AIWG input cannot be represented as full-v1')
+}
+await importShard(db, result.archive!, { blobStore, conflictStrategy: 'replace' })
+```
+
+The full converter emits all 33 authority files and native note, relationship,
+SKOS, provenance, embedding, and graph records when the AIWG source is fully
+representable. Derived, defaulted, or omitted source information returns
+`archive: null` with typed `losses`; lossy output is never labeled `full-v1`.
+
+PGlite uses the same rule for `2.0.0/full-v1`. A previously imported full
+snapshot re-exports its complete logical file set; otherwise the exporter
+materializes all 33 files from live domain tables, requires every referenced
+attachment byte, and can add an Ed25519 publisher signature. Live values that
+cannot satisfy the authority schema, including non-768-dimensional embedding
+vectors, return `archive: null` with a typed capability loss.
+
+Knowledge Shard 2.0 treats absent, `null`, empty, and non-empty values as
+distinct authority states. PGlite persists `core-v1` field presence in a
+transactional sidecar, while RecordStore carries its `record-v1` projection and
+manifest state in the same atomic batch. Wildcard fields are tracked per array
+member, such as `/attachments/0/reason`. Import rejects unsupported states
+before mutation, and export rejects legacy rows whose original presence is
+indeterminate. The pinned local matrix receipt is
+`schemas/knowledge-shard-v2.presence.receipt.json`.
 
 The AIWG index adapter accepts both `aiwg.fortemi.index.export.v1` and
 `aiwg.fortemi.index.export.v2` envelopes. The v1 record contract keeps the