Version Packages#29
Conversation
af59189 to
a1a2577
Compare
ee22e8c to
3eb1a8c
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/ficta/CHANGELOG.md`:
- Around line 79-81: Remove the duplicate 89da819 and 2dbfc1a commit links from
the Updated dependencies entry, keeping each dependency reference listed exactly
once before publishing.
- Around line 39-42: Update the changelog entry heading text to say “two
systemic classes of PII misses” instead of “two systemic PII-miss classes,”
leaving the surrounding bullets and formatting unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: ddd7a3e9-892b-44d1-b9f3-99ebf98088cb
📒 Files selected for processing (33)
.changeset/align-presidio-demo-config.md.changeset/allow-attachment-only-review.md.changeset/brave-registry-reload.md.changeset/carry-detector-spans.md.changeset/clarify-engine-protocol-boundaries.md.changeset/consolidate-release-workflow.md.changeset/detect-organization-ner.md.changeset/document-anthropic-upstream-proxy.md.changeset/explain-restored-underlines.md.changeset/harden-entity-form-boundaries.md.changeset/improve-accounting-organization-detection.md.changeset/live-registry-reload.md.changeset/map-markdown-offsets.md.changeset/markdown-case-pii-coverage.md.changeset/per-thread-trace-capture.md.changeset/pre-send-protection-review.md.changeset/preserve-surrogate-literals.md.changeset/prove-detector-outages.md.changeset/quiet-log-captures.md.changeset/quiet-pandas-protect.md.changeset/registry-authoritative-attribution.md.changeset/resolve-entity-occurrences.md.changeset/restore-highlight-scope.md.changeset/show-restored-values.md.changeset/split-role-log-dirs.md.changeset/strengthen-legal-pii-detection.md.changeset/thread-egress-evidence.md.changeset/tidy-otters-trace.md.changeset/verify-registry-publication.mdpackages/ficta/CHANGELOG.mdpackages/ficta/package.jsonpackages/protocol/CHANGELOG.mdpackages/protocol/package.json
💤 Files with no reviewable changes (29)
- .changeset/split-role-log-dirs.md
- .changeset/consolidate-release-workflow.md
- .changeset/carry-detector-spans.md
- .changeset/resolve-entity-occurrences.md
- .changeset/tidy-otters-trace.md
- .changeset/allow-attachment-only-review.md
- .changeset/map-markdown-offsets.md
- .changeset/preserve-surrogate-literals.md
- .changeset/markdown-case-pii-coverage.md
- .changeset/live-registry-reload.md
- .changeset/restore-highlight-scope.md
- .changeset/per-thread-trace-capture.md
- .changeset/align-presidio-demo-config.md
- .changeset/show-restored-values.md
- .changeset/quiet-pandas-protect.md
- .changeset/document-anthropic-upstream-proxy.md
- .changeset/prove-detector-outages.md
- .changeset/detect-organization-ner.md
- .changeset/improve-accounting-organization-detection.md
- .changeset/strengthen-legal-pii-detection.md
- .changeset/clarify-engine-protocol-boundaries.md
- .changeset/pre-send-protection-review.md
- .changeset/quiet-log-captures.md
- .changeset/verify-registry-publication.md
- .changeset/explain-restored-underlines.md
- .changeset/registry-authoritative-attribution.md
- .changeset/brave-registry-reload.md
- .changeset/thread-egress-evidence.md
- .changeset/harden-entity-form-boundaries.md
🚧 Files skipped from review as they are similar to previous changes (3)
- packages/ficta/package.json
- packages/protocol/package.json
- packages/protocol/CHANGELOG.md
| - [`f3cbc49`](https://github.com/SerovaAI/ficta/commit/f3cbc4949d9bc28f622a187e5c251d2b1a1f8cdd) Thanks [@steflsd](https://github.com/steflsd)! - Close two systemic PII-miss classes observed on markitdown-converted documents: | ||
|
|
||
| - **Markdown-aware NER input**: NLP backends (Presidio/OpenMed) now detect over compact Markdown-normalized text with exact raw-offset mapping (`**bold**`, `\_` escapes, `###` headings, list markers, `~~strike~~`), fixing contaminated spans, internal-formatting gaps, and recall lost to formatting; regex recognizers keep the raw text. | ||
| - **Case-variant coverage**: an entity detected in one casing is redacted in every casing actually present in the request (title-case prose vs ALL-CAPS headings/signature blocks), for detected PII and word/name-like registry values alike (digit-bearing secrets are never case-folded). Registry-derived variants carry `permanent` provenance, so the `detected` restore-into-tools policy withholds a secret's case twin from tool-call arguments exactly like the canonical form. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the “PII-miss” wording.
Use “two systemic classes of PII misses” instead; the current phrasing is awkward and triggers the spelling check in this user-facing changelog.
Suggested wording
- Close two systemic PII-miss classes observed on markitdown-converted documents:
+ Close two systemic classes of PII misses observed on markitdown-converted documents:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - [`f3cbc49`](https://github.com/SerovaAI/ficta/commit/f3cbc4949d9bc28f622a187e5c251d2b1a1f8cdd) Thanks [@steflsd](https://github.com/steflsd)! - Close two systemic PII-miss classes observed on markitdown-converted documents: | |
| - **Markdown-aware NER input**: NLP backends (Presidio/OpenMed) now detect over compact Markdown-normalized text with exact raw-offset mapping (`**bold**`, `\_` escapes, `###` headings, list markers, `~~strike~~`), fixing contaminated spans, internal-formatting gaps, and recall lost to formatting; regex recognizers keep the raw text. | |
| - **Case-variant coverage**: an entity detected in one casing is redacted in every casing actually present in the request (title-case prose vs ALL-CAPS headings/signature blocks), for detected PII and word/name-like registry values alike (digit-bearing secrets are never case-folded). Registry-derived variants carry `permanent` provenance, so the `detected` restore-into-tools policy withholds a secret's case twin from tool-call arguments exactly like the canonical form. | |
| - [`f3cbc49`](https://github.com/SerovaAI/ficta/commit/f3cbc4949d9bc28f622a187e5c251d2b1a1f8cdd) Thanks [`@steflsd`](https://github.com/steflsd)! - Close two systemic classes of PII misses observed on markitdown-converted documents: | |
| - **Markdown-aware NER input**: NLP backends (Presidio/OpenMed) now detect over compact Markdown-normalized text with exact raw-offset mapping (`**bold**`, `\_` escapes, `###` headings, list markers, `~~strike~~`), fixing contaminated spans, internal-formatting gaps, and recall lost to formatting; regex recognizers keep the raw text. | |
| - **Case-variant coverage**: an entity detected in one casing is redacted in every casing actually present in the request (title-case prose vs ALL-CAPS headings/signature blocks), for detected PII and word/name-like registry values alike (digit-bearing secrets are never case-folded). Registry-derived variants carry `permanent` provenance, so the `detected` restore-into-tools policy withholds a secret's case twin from tool-call arguments exactly like the canonical form. |
🧰 Tools
🪛 LanguageTool
[grammar] ~39-~39: Ensure spelling is correct
Context: ...o systemic PII-miss classes observed on markitdown-converted documents: - **Markdown-aw...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/ficta/CHANGELOG.md` around lines 39 - 42, Update the changelog entry
heading text to say “two systemic classes of PII misses” instead of “two
systemic PII-miss classes,” leaving the surrounding bullets and formatting
unchanged.
Source: Linters/SAST tools
1080f68 to
616d16e
Compare
616d16e to
f117c42
Compare
This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to main, this PR will be updated.
Releases
@serovaai/ficta@0.2.0
Minor Changes
#60
083e548Thanks @steflsd! - Enable context-bound entity-family surrogates for structured entities in trusted keyed request bodies and document their metadata boundary.2dbfc1aThanks @steflsd! - Add live managed-registry reloads and Markdown-aware PII case coverage.#40
726f504Thanks @steflsd! - Enforce strict managed-registry contracts and separate engine, proxy, protocol, and Gateway responsibilities.#58
b6c2cdfThanks @steflsd! - Link unique high-confidence organization aliases to registered entity anchors and report values-free ambiguity counts in protection stats and egress proofs.7c8272cThanks @steflsd! - Standardize validation commands oncheck, replacing theverifyandverify:*scripts.#50
60cc3a5Thanks @steflsd! - Move legal identity recognition into the Presidio sidecar, preserve structured regex protection, and add values-free trace diagnostics.#59
9031dadThanks @steflsd! - Add gated context-bound entity-family surrogate rendering and exact restoration across buffered, streaming, and tool-call transports.#56
e465e5aThanks @steflsd! - Introduce the entity-aware managed registry v1 contract with explicit form boundaries, strict whole-registry validation, and restart-safe live reloads.#66
efe1203Thanks @steflsd! - Observe residual surrogate tokens that survive restore. A surrogate-shaped token with no dictionary mapping — mutated, truncated, or invented by the model (e.g. a wildcard entity-family reference likeFICTA_ORG_<entityTag>_*) — is now counted per response and surfaced as a values-free total in the proxy log (⚠️ N unrestored surrogate token(s)),protection-stats.json, and the stats summary. Detection covers opaque, typed, and entity-family token shapes plus entity-family prefix fragments, across buffered, streamed, and SSE restore paths. Observe-only: response bytes are unchanged, and restore remains exact-match — unknown tokens are never fuzzily recovered.#79
b96f1b0Thanks @steflsd! - Country-scoped Presidio registry. The shipped recognizer config (renamedpresidio/default_recognizers.za.yaml→presidio/default_recognizers.yaml) is now fullycountry-tagged, and the sidecar's
FICTA_PRESIDIO_SUPPORTED_COUNTRIESenv var (defaultza,us,mu,the SA-legal reference profile) decides at load time which country-specific recognizers run;
locale-agnostic recognizers always load. Notably, the UK NHS recognizer no longer runs on default
traffic — add
ukto the country scope for UK-matter deployments.FICTA_PII_PRESIDIO_ENTITIESis now a pure optional narrowing allowlist: when unset,
/analyzerequests omit theentitiesfield and the deployment's loaded registry is the detection surface. The proxy also now strips
every inbound
x-ficta-*header before forwarding upstream, instead of enumerating known ones.#42
35b2e33Thanks @steflsd! - Add a runtime-admin grant for per-chat raw trace capture and decouple capture from log verbosity.Patch Changes
b19cf46Thanks @steflsd! - Align source-checkout Presidio startup, logging-root configuration, and documented runtime defaults.#41
1bd5178Thanks @steflsd! - Allow attachment-only Gateway drafts to enter protection review or send with the existing generic review instruction.2f3bf7fThanks @steflsd! - Carry transient UTF-16 source spans through the PII detector contract for offset-based redaction.737e967Thanks @steflsd! - Consolidate CI, secret scanning, and release automation into one gated workflow run.0b26f15Thanks @steflsd! - Detect organization names via Presidio NER. Ship an NLP-engine config (presidio/nlp_engine.za.yaml, mounted asNLP_CONF_FILE) that un-suppressesORGANIZATION— upstream ignores it as "many false positives" — so unregistered client/counterparty/company names get a best-effort catch from spaCyen_core_web_lg. This is probabilistic and over-redacts (headings, common nouns); exact confidentiality still comes from the registered-value registry.af9dea2Thanks @steflsd! - Document routingficta claudethrough a local Anthropic-compatible proxy viaFICTA_ANTHROPIC_UPSTREAM, so an alt model (e.g. GPT‑5.6 "sol" behind CLIProxyAPI on a ChatGPT subscription) can run with redaction intact. Loopback upstreams need noFICTA_ALLOW_CUSTOM_UPSTREAM.#48
6dd6b82Thanks @steflsd! - Explain restored-value underlines with accessible origin-specific tooltips.e2eb4a4Thanks @steflsd! - Redact embedded case variants of registered and detected entities and add explicit boundary policy for future aliases.bd8448eThanks @steflsd! - Improve Presidio organization coverage for accounting tables and same-document business variants while filtering structural NER false positives.f3cbc49Thanks @steflsd! - Live protected registry: values published from the gateway admin UI take effect in the running proxy without a restart. NewPOST /__ficta/registry/reload(loopback-gated, request body ignored, counts-only response includingskippedTooShortfor values belowFICTA_REGISTRY_MIN_LEN),ProtectionEngine.reloadRegistryValues()registering new managed-file values into the live vault, and a stat-based cache key for the managed-registry plugin (a rewritten file is actually re-read — also fixes stale registry counts in per-request log metadata andficta doctor). Additions are live; deletions still apply on restart (removing a value mid-process would break restore of surrogates already in transcripts). Protocol gainsFICTA_REGISTRY_RELOAD_PATH,RegistryReloadOk/Error, andisRegistryReloadOk.ee44595Thanks @steflsd! - Map compact Markdown detection offsets back to raw request ranges so internally formatted entities are fully redacted.f3cbc49Thanks @steflsd! - Close two systemic PII-miss classes observed on markitdown-converted documents:**bold**,\_escapes,###headings, list markers,~~strike~~), fixing contaminated spans, internal-formatting gaps, and recall lost to formatting; regex recognizers keep the raw text.permanentprovenance, so thedetectedrestore-into-tools policy withholds a secret's case twin from tool-call arguments exactly like the canonical form.#70
64335d9Thanks @steflsd! - Neutralize caller-provenance labels: explicit pre-send selections are now recorded withsource: "user-selected"andplugin: "protection-preview"(previouslygateway-user/gateway-preview). The strings appear in protection-preview findings, traces, and stats labels;no behavior depends on them.
#34
50a49f7Thanks @steflsd! - Add a gateway trace-capture header so raw proxy trace/audit capture can be scoped per chat thread.2d55f15Thanks @steflsd! - Add a loopback-only pre-send protection preview with resolver-authored spans and content-bound, single-use tickets for user-selected chat protections.0b26f15Thanks @steflsd! - Add an opt-inFICTA_PRESERVE_LITERALSmode that injects a system/developer instruction carrying the exact surrogate tokens present in each outbound request, telling the model to reproduce them verbatim. This improves restore reliability: models otherwise truncate or editorialise long opaque tokens (FICTA_62a02923…), which leaves them unrestorable. The instruction only ever adds surrogate tokens the proxy already minted (never raw values) and runs after the fail-closed leak gate.f195c54Thanks @steflsd! - Record fail-closed detector outages across body, query, and header surfaces as explicit values-free blocked-request proof events.aacf45dThanks @steflsd! - Keep published documentation focused on shipped behavior and public threat-model boundaries, with private strategy and future-roadmap material maintained separately.#39
b60f2bfThanks @steflsd! - Move request captures into lazyruns/run-*directories and write current protection stats toprotection-stats.json.89da819Thanks @steflsd! - Enforce required-registry readiness on standalone provider traffic and expose the blocking state to Gateway.#74
f640551Thanks @steflsd! - Skip Doppler registry API and secret-loading commands when the launch directory has no resolvable Doppler scope.f3cbc49Thanks @steflsd! - Audit attribution now prefers the registry's identity when a value is both a registered secret and a probabilistic detection: the trace/stats reportenv-file / secret / exact(e.g.CLIENT_CFO) instead of the detector's guess (person / pii / high). Reporting only — span selection, surrogates, restore, and restore-into-tools provenance are unchanged.7202694Thanks @steflsd! - Resolve overlapping body entities by source spans so registered values win exact boundaries without partial leaks.f3cbc49Thanks @steflsd! - Scope trace-mode restore-highlight markers to assistant output. The highlight triple (the gateway's show/hide toggle format) now rides only on streamed text fragments and their sibling fields; metadata/replay events that echo the request back (response.created/response.in_progressinstructions) restore plainly — surrogates still never reach the client, but the echoed preamble is no longer littered with marker sentinels.7625390Thanks @steflsd! - Restore repeated document-linked short organization aliases in Presidio identity detection.#47
2f799b0Thanks @steflsd! - Highlight locally restored response values without requiring sensitive trace capture.e79624eThanks @steflsd! - Separate capture logs by proxy role so concurrent instances no longer share one directory. Thestandalone/web server now writes under
~/.ficta/logs/gateway/, and eachficta <agent>shim under~/.ficta/logs/agents/<agent>/<instance>/(one subtree per process, so twoficta claudesessionsnever interleave
runs/or raceprotection-stats.json). SetFICTA_LOG_ROOTto relocate the root;FICTA_LOG_DIRstill fully overrides the exact path. Existingconfig.tomlfiles whose[logging].log_direquals the default root are treated as neutral so the split applies.1ae6497Thanks @steflsd! - Preserve contained PII candidates for occurrence resolution and add legal-document ID, Mauritius phone, and ordinal-date Presidio coverage.8c09e18Thanks @steflsd! - Add values-free, per-thread provider-egress evidence for Gateway chats.89da819Thanks @steflsd! - Simplify the documented POC configuration and have setup emit only the canonical multi-backend PII setting.2dbfc1aThanks @steflsd! - Harden live Protected Registry publication: Gateway now writes private registry files atomically, serializes publish transactions, and verifies a per-generation revision echoed by the proxy together with managed-source health counts. Hosted Gateway deployments are explicitly bound to one WorkOS organization viaFICTA_GATEWAY_ORG_ID, matching the proxy's process-global permanent registry.Updated dependencies [
083e548,1bd5178,2dbfc1a,726f504,737e967,af9dea2,b6c2cdf,f3cbc49,50a49f7,2d55f15,f195c54,aacf45d,7c8272c,89da819,9031dad,e465e5a,efe1203,2f799b0,b96f1b0,8c09e18,35b2e33,89da819,2dbfc1a]:@serovaai/ficta-protocol@0.2.0
Minor Changes
#60
083e548Thanks @steflsd! - Enable context-bound entity-family surrogates for structured entities in trusted keyed request bodies and document their metadata boundary.2dbfc1aThanks @steflsd! - Add live managed-registry reloads and Markdown-aware PII case coverage.#40
726f504Thanks @steflsd! - Enforce strict managed-registry contracts and separate engine, proxy, protocol, and Gateway responsibilities.#58
b6c2cdfThanks @steflsd! - Link unique high-confidence organization aliases to registered entity anchors and report values-free ambiguity counts in protection stats and egress proofs.7c8272cThanks @steflsd! - Standardize validation commands oncheck, replacing theverifyandverify:*scripts.#59
9031dadThanks @steflsd! - Add gated context-bound entity-family surrogate rendering and exact restoration across buffered, streaming, and tool-call transports.#56
e465e5aThanks @steflsd! - Introduce the entity-aware managed registry v1 contract with explicit form boundaries, strict whole-registry validation, and restart-safe live reloads.#79
b96f1b0Thanks @steflsd! - Country-scoped Presidio registry. The shipped recognizer config (renamedpresidio/default_recognizers.za.yaml→presidio/default_recognizers.yaml) is now fullycountry-tagged, and the sidecar's
FICTA_PRESIDIO_SUPPORTED_COUNTRIESenv var (defaultza,us,mu,the SA-legal reference profile) decides at load time which country-specific recognizers run;
locale-agnostic recognizers always load. Notably, the UK NHS recognizer no longer runs on default
traffic — add
ukto the country scope for UK-matter deployments.FICTA_PII_PRESIDIO_ENTITIESis now a pure optional narrowing allowlist: when unset,
/analyzerequests omit theentitiesfield and the deployment's loaded registry is the detection surface. The proxy also now strips
every inbound
x-ficta-*header before forwarding upstream, instead of enumerating known ones.#42
35b2e33Thanks @steflsd! - Add a runtime-admin grant for per-chat raw trace capture and decouple capture from log verbosity.Patch Changes
#41
1bd5178Thanks @steflsd! - Allow attachment-only Gateway drafts to enter protection review or send with the existing generic review instruction.737e967Thanks @steflsd! - Consolidate CI, secret scanning, and release automation into one gated workflow run.af9dea2Thanks @steflsd! - Document routingficta claudethrough a local Anthropic-compatible proxy viaFICTA_ANTHROPIC_UPSTREAM, so an alt model (e.g. GPT‑5.6 "sol" behind CLIProxyAPI on a ChatGPT subscription) can run with redaction intact. Loopback upstreams need noFICTA_ALLOW_CUSTOM_UPSTREAM.f3cbc49Thanks @steflsd! - Live protected registry: values published from the gateway admin UI take effect in the running proxy without a restart. NewPOST /__ficta/registry/reload(loopback-gated, request body ignored, counts-only response includingskippedTooShortfor values belowFICTA_REGISTRY_MIN_LEN),ProtectionEngine.reloadRegistryValues()registering new managed-file values into the live vault, and a stat-based cache key for the managed-registry plugin (a rewritten file is actually re-read — also fixes stale registry counts in per-request log metadata andficta doctor). Additions are live; deletions still apply on restart (removing a value mid-process would break restore of surrogates already in transcripts). Protocol gainsFICTA_REGISTRY_RELOAD_PATH,RegistryReloadOk/Error, andisRegistryReloadOk.#34
50a49f7Thanks @steflsd! - Add a gateway trace-capture header so raw proxy trace/audit capture can be scoped per chat thread.2d55f15Thanks @steflsd! - Add a loopback-only pre-send protection preview with resolver-authored spans and content-bound, single-use tickets for user-selected chat protections.f195c54Thanks @steflsd! - Record fail-closed detector outages across body, query, and header surfaces as explicit values-free blocked-request proof events.aacf45dThanks @steflsd! - Keep published documentation focused on shipped behavior and public threat-model boundaries, with private strategy and future-roadmap material maintained separately.89da819Thanks @steflsd! - Enforce required-registry readiness on standalone provider traffic and expose the blocking state to Gateway.#66
efe1203Thanks @steflsd! - Observe residual surrogate tokens that survive restore. A surrogate-shaped token with no dictionary mapping — mutated, truncated, or invented by the model (e.g. a wildcard entity-family reference likeFICTA_ORG_<entityTag>_*) — is now counted per response and surfaced as a values-free total in the proxy log (⚠️ N unrestored surrogate token(s)),protection-stats.json, and the stats summary. Detection covers opaque, typed, and entity-family token shapes plus entity-family prefix fragments, across buffered, streamed, and SSE restore paths. Observe-only: response bytes are unchanged, and restore remains exact-match — unknown tokens are never fuzzily recovered.#47
2f799b0Thanks @steflsd! - Highlight locally restored response values without requiring sensitive trace capture.8c09e18Thanks @steflsd! - Add values-free, per-thread provider-egress evidence for Gateway chats.89da819Thanks @steflsd! - Simplify the documented POC configuration and have setup emit only the canonical multi-backend PII setting.2dbfc1aThanks @steflsd! - Harden live Protected Registry publication: Gateway now writes private registry files atomically, serializes publish transactions, and verifies a per-generation revision echoed by the proxy together with managed-source health counts. Hosted Gateway deployments are explicitly bound to one WorkOS organization viaFICTA_GATEWAY_ORG_ID, matching the proxy's process-global permanent registry.