@fortemi/core 2026.7.12 → 2026.7.13

package/README.md

@@ -133,6 +133,7 @@ Knowledge Shard conversion intentionally lives on the build-oriented subpath:
 import {
   aiwgFortemiIndexFromKnowledgeShard,
   aiwgFortemiIndexToKnowledgeShard,
+  aiwgFortemiIndexToKnowledgeShardWithReport,
 } from '@fortemi/core/aiwg-index-shard'
 ```
 
@@ -140,6 +141,41 @@ 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
 existing flat fields for filtering and search: `facets`, `tags`, `concepts`,