@happyvertical/smrt-facts 0.53.5 → 0.54.1

package/README.md

@@ -248,3 +248,43 @@ the migration/backfill instruction, retaining the original error as cause.
 `Fact` declares `catalog_search` as its permitted final derived column; custom
 normalization must preserve that declaration and cannot replace framework
 identity, tenant, revision or conflict columns.
+
+### Reconciliation access scopes
+
+`reconcile({ rawInput, tenantId, accessScope: 'public' })` partitions candidates
+by both tenant and an exact, application-defined scope token. Exact matching and
+semantic ranking exclude other scopes before candidate text is hydrated or sent
+to disambiguation. Created facts and evolution branches retain that scope;
+`branch()` rejects an explicit scope change. Use public collection predicates
+such as `facts.list({ where: { tenantId, accessScope: 'public' } })` and scoped
+`get()` calls when reusing results. Generic catalog and evolution APIs do not
+implicitly authorize a scope: the application must authorize access and apply
+its scope predicate before returning evidence or associating article facts.
+
+Tokens are case-sensitive, nonblank strings of at most 256 characters without
+control characters or unpaired surrogates. They are partition identifiers, **not authorization
+credentials**. Applications must derive them from trusted authorization state;
+never accept an arbitrary client-selected token as permission to read a scope.
+A fact must only aggregate sources with the visibility represented by its scope.
+Source metadata does not establish candidate visibility.
+
+`accessScope` is server-managed: generated REST/MCP create and update inputs
+strip it while allowing ordinary writable fields. Trusted server-side
+`FactCollection.create()`, `reconcile()` and `branch()` retain persistence access.
+Owner-authorized migration code can assign the field and call `save()` in a
+controlled system context with reconciliation writers stopped; no generated
+reclassification endpoint is exposed. Do not expose that operator procedure or
+forward untrusted request bodies to direct collection writes.
+
+Run the standard `smrt db:migrate` before deploying writers using this field.
+The nullable `Fact.accessScope` column leaves existing rows unclassified.
+Omitting `accessScope` (or passing `null`) searches only this legacy NULL
+partition; explicit scopes never include legacy rows. No migration guesses
+visibility from provenance metadata. Classify legacy facts only through an
+owner-authorized data migration with reconciliation writers stopped, or leave them separate and re-extract into the
+appropriate scope. A scope change is not an ordinary reconciliation operation.
+
+PostgreSQL reconciliation retains its transactional fact/source write and
+per-identity lock. SQLite retains its existing partial-write contract: a failed
+source write may leave the fact, and retry finds the same scoped exact fact.
+Do not record an application extraction receipt until all writes succeed.

package/dist/fact.d.ts

@@ -22,6 +22,8 @@ export declare class Fact extends SmrtObject {
     type: string;
     status: string;
     domain: string;
+    /** Opaque reconciliation partition; NULL denotes unclassified legacy data. */
+    accessScope: string | null;
     /**
      * Self-referencing pointer to the predecessor fact in an evolution chain.
      *

package/dist/fact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fact.d.ts","sourceRoot":"","sources":["../src/fact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAqB,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAG/E,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,EACT,MAAM,SAAS,CAAC;AAWjB,qBAgBa,IAAK,SAAQ,UAAU;IAElC,WAAW,EAAE,MAAM,CAAM;IAGzB,OAAO,EAAE,MAAM,CAAM;IAErB,2EAA2E;IAE3E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAQ;IAGpC,IAAI,EAAE,MAAM,CAAe;IAG3B,MAAM,EAAE,MAAM,CAAa;IAG3B,MAAM,EAAE,MAAM,CAAM;IAEpB;;;;;;;OAOG;IAEH,cAAc,EAAE,MAAM,CAAM;IAG5B,aAAa,EAAE,MAAM,CAAc;IAGnC,WAAW,EAAE,MAAM,CAAK;IAGxB,UAAU,EAAE,MAAM,CAAO;IAGzB,QAAQ,EAAE,MAAM,CAAM;IAGtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAG/B,SAAS,EAAE,IAAI,CAAc;IAE7B,SAAS,EAAE,IAAI,CAAc;gBAEjB,OAAO,GAAE,WAAgB;cAwBlB,4BAA4B,IAAI,SAAS,MAAM,EAAE;cAIjD,wBAAwB,CACzC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAc1B,WAAW,IAAI,YAAY;IAW3B,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAIrC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAMpD,OAAO,IAAI,QAAQ;IAInB,SAAS,IAAI,UAAU;IAIvB,gBAAgB,IAAI,aAAa;IAIjC,QAAQ,IAAI,OAAO;IAInB,YAAY,IAAI,OAAO;IAIvB;;;;;;OAMG;IACH,cAAc,IAAI,OAAO;IAIzB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAQ5C;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAMtC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,eAAe,EAAE,UAAU,EAAE,CAAC;IAMjE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,gBAAgB,EAAE,WAAW,EAAE,CAAC;CAKrE"}
+{"version":3,"file":"fact.d.ts","sourceRoot":"","sources":["../src/fact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAqB,UAAU,EAAQ,MAAM,0BAA0B,CAAC;AAG/E,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,EACV,QAAQ,EACT,MAAM,SAAS,CAAC;AAWjB,qBAgBa,IAAK,SAAQ,UAAU;IAElC,WAAW,EAAE,MAAM,CAAM;IAGzB,OAAO,EAAE,MAAM,CAAM;IAErB,2EAA2E;IAE3E,aAAa,EAAE,MAAM,GAAG,IAAI,CAAQ;IAGpC,IAAI,EAAE,MAAM,CAAe;IAG3B,MAAM,EAAE,MAAM,CAAa;IAG3B,MAAM,EAAE,MAAM,CAAM;IAEpB,8EAA8E;IAE9E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;IAElC;;;;;;;OAOG;IAEH,cAAc,EAAE,MAAM,CAAM;IAG5B,aAAa,EAAE,MAAM,CAAc;IAGnC,WAAW,EAAE,MAAM,CAAK;IAGxB,UAAU,EAAE,MAAM,CAAO;IAGzB,QAAQ,EAAE,MAAM,CAAM;IAGtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAG/B,SAAS,EAAE,IAAI,CAAc;IAE7B,SAAS,EAAE,IAAI,CAAc;gBAEjB,OAAO,GAAE,WAAgB;cA0BlB,4BAA4B,IAAI,SAAS,MAAM,EAAE;cAIjD,wBAAwB,CACzC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACtC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAc1B,WAAW,IAAI,YAAY;IAW3B,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAIrC,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAMpD,OAAO,IAAI,QAAQ;IAInB,SAAS,IAAI,UAAU;IAIvB,gBAAgB,IAAI,aAAa;IAIjC,QAAQ,IAAI,OAAO;IAInB,YAAY,IAAI,OAAO;IAIvB;;;;;;OAMG;IACH,cAAc,IAAI,OAAO;IAIzB;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAQ5C;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAMtC;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,eAAe,EAAE,UAAU,EAAE,CAAC;IAMjE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,OAAO,gBAAgB,EAAE,WAAW,EAAE,CAAC;CAKrE"}

package/dist/facts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../src/facts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../src/facts.ts"],"names":[],"mappings":"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"}