Skip to content
Merged
Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
103 commits
Select commit Hold shift + click to select a range
967a3af
docs(plan): specify enterprise explicit-value parser
seonghobae Aug 4, 2026
851837e
feat(enterprise): add deterministic explicit-value parser
seonghobae Aug 4, 2026
f5148d8
feat(enterprise): export explicit-value parser contracts
seonghobae Aug 4, 2026
1d09b67
test(enterprise): verify explicit-value parsing and privacy
seonghobae Aug 4, 2026
8bb61a8
docs(enterprise): document explicit-value parser boundaries
seonghobae Aug 4, 2026
1cb6009
docs(changelog): add enterprise parser release note
seonghobae Aug 4, 2026
322da69
ci: add one-shot PR 533 autofix
seonghobae Aug 4, 2026
7ab32a2
fix(enterprise): close parser validation gaps
github-actions[bot] Aug 4, 2026
24fad2e
docs(enterprise): document structured decimal validation
seonghobae Aug 4, 2026
4046e6b
ci: retrigger exact-head validation
seonghobae Aug 4, 2026
00ddba8
ci: validate repaired exact head
seonghobae Aug 4, 2026
606a0da
ci: harden PR 533 payload validation
seonghobae Aug 4, 2026
ad3cdd6
ci: repair payload hardening workflow
seonghobae Aug 4, 2026
ffb8459
ci: simplify payload hardening workflow
seonghobae Aug 4, 2026
2058411
fix(enterprise): harden explicit payload validation
github-actions[bot] Aug 4, 2026
c2a5917
ci: retrigger hardened exact head
seonghobae Aug 4, 2026
5fe53a1
ci: validate hardened exact head
seonghobae Aug 4, 2026
fbd4b02
docs(enterprise): record fail-closed payload validation
seonghobae Aug 4, 2026
ced912d
ci: validate PR 533 provider output
seonghobae Aug 4, 2026
a9d82b7
fix(enterprise): validate explicit parser output
github-actions[bot] Aug 4, 2026
95e21ae
ci: add one-shot provider boundary hardening
seonghobae Aug 4, 2026
857980e
ci: trigger provider boundary hardening
seonghobae Aug 4, 2026
bfbbfd3
ci: repair PR 533 provider hardening
seonghobae Aug 4, 2026
28d85c3
fix(enterprise): validate provider parser output
github-actions[bot] Aug 4, 2026
040d7a7
ci: validate provider-hardened exact head
seonghobae Aug 4, 2026
11e656e
ci: repair PR 533 metadata indentation
seonghobae Aug 4, 2026
17c385d
fix(enterprise): restore metadata validation indentation
github-actions[bot] Aug 4, 2026
856daf6
ci: stage PR 533 indentation repair
seonghobae Aug 4, 2026
6dd2ad6
ci: trigger metadata indentation repair
seonghobae Aug 4, 2026
a8c08a7
docs(enterprise): specify provider output validation
seonghobae Aug 4, 2026
5850eef
ci: remove completed indentation repair workflow
seonghobae Aug 4, 2026
25845ff
ci: validate repaired provider boundary
seonghobae Aug 4, 2026
0ced3f7
docs(enterprise): enumerate provider validation tests
seonghobae Aug 5, 2026
6deb609
ci: stage provider exception hardening
seonghobae Aug 5, 2026
40e23af
ci: trigger provider exception hardening
seonghobae Aug 5, 2026
36e6541
ci: trigger provider exception hardening
seonghobae Aug 5, 2026
1c8b626
ci: repair provider exception hardening
seonghobae Aug 5, 2026
f50584a
ci: simplify provider exception hardening
seonghobae Aug 5, 2026
d3218b6
ci: trigger provider exception hardening
seonghobae Aug 5, 2026
2a8aa19
ci: trigger provider boundary hardening
seonghobae Aug 5, 2026
b62305b
ci: trigger provider boundary hardening
seonghobae Aug 5, 2026
d9911b3
chore: trigger provider boundary hardening
seonghobae Aug 5, 2026
e319f57
ci: trigger provider hardening on ready review
seonghobae Aug 5, 2026
e1318f5
ci: add one-shot provider hardening helper
seonghobae Aug 5, 2026
4ef6670
ci: prepare provider hardening runtime
seonghobae Aug 5, 2026
422bd39
ci: run provider hardening on PR synchronization
seonghobae Aug 5, 2026
4edc689
ci: fix exact-head provider hardening helper
seonghobae Aug 5, 2026
36ba330
ci: prepare provider hardening runtime
seonghobae Aug 5, 2026
8ae45a6
ci: validate provider hardening with locked test dependencies
seonghobae Aug 5, 2026
c5b00b6
ci: repair provider hardening callback generation
seonghobae Aug 5, 2026
5713d19
fix(enterprise): seal provider trust boundary
github-actions[bot] Aug 5, 2026
ed2184f
ci: retrigger provider-hardened validation
seonghobae Aug 5, 2026
56f29e4
docs: record provider boundary hardening
seonghobae Aug 5, 2026
07a0455
ci: validate provider-hardened exact head
seonghobae Aug 5, 2026
4cba5dc
docs: synchronize provider hardening changelog
seonghobae Aug 5, 2026
0e6b935
ci: apply verified explicit-value review fixes
seonghobae Aug 5, 2026
3e0243b
ci: repair explicit-value review fixture
seonghobae Aug 5, 2026
943e92d
fix(review): address CodeRabbit parser findings
seonghobae Aug 5, 2026
ffc4114
fix(review): address CodeRabbit parser findings
seonghobae Aug 5, 2026
5683236
ci: remove failed review repair workflow
seonghobae Aug 5, 2026
4a799fb
ci: remove superseded review hardening workflow
seonghobae Aug 5, 2026
ba69101
ci: remove superseded review fixes workflow
seonghobae Aug 5, 2026
ffbc1ca
ci: remove stale review-fix trigger
seonghobae Aug 5, 2026
553f7db
chore: stage deterministic review fix script
seonghobae Aug 5, 2026
f27e640
ci: run deterministic PR 533 review fixes
seonghobae Aug 5, 2026
0e74378
ci: run deterministic PR 533 review fixes
seonghobae Aug 5, 2026
598b28c
ci: repair PR 533 review workflow syntax
seonghobae Aug 5, 2026
c043d9b
ci: run deterministic PR 533 review fixes
seonghobae Aug 5, 2026
49890e2
ci: run accepted PR 533 review fixes
seonghobae Aug 5, 2026
b2354b7
ci: format accepted PR 533 review fixes before validation
seonghobae Aug 5, 2026
165c63e
ci: retrigger accepted PR 533 review fixes
seonghobae Aug 5, 2026
557c2fd
ci: complete verified PR 533 review remediation
seonghobae Aug 5, 2026
b08ac01
ci: install PR 533 focused coverage tooling
seonghobae Aug 5, 2026
f096349
ci: run focused coverage without package import aliasing
seonghobae Aug 5, 2026
cc10f9b
ci: isolate PR 533 review validation
seonghobae Aug 5, 2026
3403f41
test: cover explicit-value payload guard branches
seonghobae Aug 5, 2026
83eca8f
test: stage PR 533 branch-coverage fixes
seonghobae Aug 5, 2026
8625b95
ci: repair targeted payload coverage workflow syntax
seonghobae Aug 5, 2026
a770192
ci: cover defensive PR 533 review branches
seonghobae Aug 5, 2026
3a738f7
fix(enterprise): address explicit-value review findings
github-actions[bot] Aug 5, 2026
febf376
ci: remove temporary PR 533 repair workflow
seonghobae Aug 5, 2026
fc44b59
chore: remove PR 533 repair trigger
seonghobae Aug 5, 2026
5677dc7
chore: remove temporary PR 533 coverage helper
seonghobae Aug 5, 2026
71da90f
chore: remove temporary PR 533 review helper
seonghobae Aug 5, 2026
b8183dc
test: cover remaining explicit-value payload branches
seonghobae Aug 5, 2026
6ab8cfd
ci: apply final explicit-value branch tests
seonghobae Aug 5, 2026
e05fb08
ci: avoid blank line at test file EOF
seonghobae Aug 5, 2026
b038035
test(enterprise): cover remaining explicit-value branches
github-actions[bot] Aug 5, 2026
7ec03f5
chore(ci): remove completed PR 533 review fixer
seonghobae Aug 5, 2026
01f33a6
ci: restore immutable changelog history for PR 533
seonghobae Aug 5, 2026
37b5ebe
fix(changelog): restore immutable release history
github-actions[bot] Aug 5, 2026
afd9ace
chore(ci): remove completed changelog restorer
seonghobae Aug 5, 2026
872e2ee
ci: restore PR 533 changelog history
seonghobae Aug 5, 2026
8766b88
docs: restore complete changelog history
github-actions[bot] Aug 5, 2026
c084865
docs: clarify explicit-value offset boundary
seonghobae Aug 5, 2026
eaa6011
ci: synchronize PR 533 changelog
seonghobae Aug 5, 2026
1963676
docs: synchronize explicit-value changelog fragment
github-actions[bot] Aug 5, 2026
3ae2bcc
ci: render PR 533 changelog parity
seonghobae Aug 5, 2026
0a72280
docs: require changelog synchronization after fragment changes
seonghobae Aug 5, 2026
efb459d
docs(changelog): render explicit-value parser fragment
github-actions[bot] Aug 5, 2026
8d62d69
docs: mark changelog parity as merge gate
seonghobae Aug 5, 2026
acb3569
docs(plan): record exact-head verification gate
seonghobae Aug 5, 2026
1e194b3
chore(ci): refresh exact-head protected checks
seonghobae Aug 5, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 87 additions & 0 deletions .github/workflows/pr-533-autofix.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
name: PR 533 one-shot autofix

on:
push:
branches:
- feat/enterprise-explicit-value-parser

permissions:
contents: write
Comment thread
github-advanced-security[bot] marked this conversation as resolved.
Fixed

concurrency:
group: pr-533-one-shot-autofix
cancel-in-progress: false

jobs:
fix:
if: github.repository == 'ContextualWisdomLab/fast-mlsirm'
runs-on: ubuntu-24.04
timeout-minutes: 20
steps:
- name: Check out exact branch head
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
ref: feat/enterprise-explicit-value-parser
fetch-depth: 0

- name: Configure Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97
with:
python-version: '3.12'

- name: Apply structured validation and render changelog
shell: bash
run: |
set -euo pipefail
python - <<'PY'
from pathlib import Path

path = Path("python/fast_mlsirm/scoring/enterprise_issue/explicit_values.py")
text = path.read_text(encoding="utf-8")
before = '''def _decimal_amount(value: str, path: str) -> str:
"""Return exact finite nonnegative decimal text without float conversion."""
try:
amount = Decimal(value.replace(",", ""))
'''
after = '''def _decimal_amount(value: str, path: str) -> str:
"""Return exact finite nonnegative decimal text without float conversion."""
if type(value) is not str:
raise assessment_error(
"invalid_decimal_amount",
path,
"decimal amount must use the accepted nonnegative decimal grammar",
)
try:
amount = Decimal(value.replace(",", ""))
'''
if before not in text:
raise SystemExit("expected _decimal_amount implementation was not found")
path.write_text(text.replace(before, after, 1), encoding="utf-8")
PY
python scripts/render_changelog_fragments.py --update CHANGELOG.md
python scripts/render_changelog_fragments.py --check CHANGELOG.md

- name: Install focused test dependencies
shell: bash
run: |
set -euo pipefail
python -m pip install --require-hashes -r requirements/ci.txt
python -m pip install --no-deps --no-build-isolation -e .

- name: Verify focused regressions
shell: bash
run: |
set -euo pipefail
pytest tests/test_scoring_enterprise_explicit_values.py tests/test_changelog_fragment_contract.py

- name: Commit fixes and remove one-shot workflow
shell: bash
run: |
set -euo pipefail
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git rm .github/workflows/pr-533-autofix.yml
git add CHANGELOG.md python/fast_mlsirm/scoring/enterprise_issue/explicit_values.py
git diff --cached --check
git commit -m "fix(enterprise): close parser validation gaps"
git push origin HEAD:feat/enterprise-explicit-value-parser
18 changes: 18 additions & 0 deletions docs/changelog.d/enterprise-explicit-value-parser.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Deterministic enterprise explicit-value parser

## Added

- Added a provider-neutral deterministic parser for verified explicit calendar
dates, marked deadlines, allowlisted currency amounts, recurrence frequencies,
and labeled customer or account identifiers under
`fast_mlsirm.scoring.enterprise_issue`.
- Added exact source fingerprint and Python Unicode-code-point-count replay,
UTF-8 span fingerprints, deterministic deadline precedence, overlap rejection,
bounded output, and hashed identifier payloads without retaining source text or
clear-text customer identifiers.
- Added immutable content-addressed records that compile exact occurrences into
the existing directly stated `EvidenceSpanRecord` boundary without adding a
parallel scoring, observation, result, or engine schema.
- Added deterministic, protocol, privacy, security, exact-decimal, offset,
ordering-invariance, metamorphic sentiment-independence, and fail-closed tests,
plus APA 7th standards traceability and conservative interpretation limits.
73 changes: 68 additions & 5 deletions docs/enterprise_issue_evidence_contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
`fast_mlsirm.scoring.enterprise_issue` provides the first provider-neutral domain
boundary for issue #404. The module stores content identities, exact source-span
offsets, epistemic roles, stakeholder perspectives, candidate-intervention
provenance, and criterion-level request provenance without retaining raw
enterprise text.
provenance, deterministic explicit values, and criterion-level request provenance
without retaining raw enterprise text.

## Contract boundary

Expand All @@ -28,6 +28,51 @@ authorized source system and pass SHA-256 content fingerprints plus offsets.
Sensitive metadata fields already prohibited by the shared scoring contract are
rejected here as well.

## Deterministic explicit-value parser

`DeterministicExplicitValueParser` adds a narrow auditable boundary for values
that are already explicit in authorized source text. Its first grammar recognizes:

- Gregorian calendar dates in extended `YYYY-MM-DD` form;
- deadlines marked by `due`, `deadline`, `by`, or `no later than`;
- exact nonnegative decimal amounts preceded by a caller-allowlisted uppercase
three-letter currency code;
- positive recurrence counts per day, week, month, quarter, or year; and
- customer or account identifiers introduced by an explicit identifier label.

The parser verifies the transient text against the exact
`EnterpriseSourceRecord.source_content_fingerprint` and Python string character
count before extraction. Match offsets are Python Unicode-code-point indices,
which are appropriate for replaying slices of the same Python `str`; they are not
UTF-8 byte offsets or user-perceived grapheme-cluster positions. Every persisted
span also carries SHA-256 over the exact UTF-8 bytes of the matched slice.

Deadline matches supersede the calendar-date match embedded inside the same
marked deadline. Any other accepted overlap fails closed rather than multiplying
one occurrence into several evidence records. Output order and parser revision
identity are deterministic and independent of caller currency-code ordering.

Money normalization constructs `Decimal` directly from accepted text after
removing validated grouping commas; it never passes through binary floating
point. Calendar dates are validated with `date.fromisoformat()` only after the
strict extended-date grammar has matched. Currency membership remains a caller
governance responsibility: an uppercase three-letter token is accepted only when
it occurs in the parser's explicit allowlist, and the parser does not claim that a
caller-supplied list is complete or current.

Clear-text customer and account identifiers are replaced with SHA-256 before a
public record is constructed. Raw source text and clear-text identifiers are not
retained in `ExplicitValueRecord`, its evidence projection, or serialized output.
`ExplicitValueRecord.to_evidence_span()` marks an exact occurrence as a directly
stated fact. This means only that the matched text was present in the verified
source revision; it does not establish that the value is true, current, material,
probable, decision-relevant, or causally related to an outcome.

The parser is deliberately not a semantic issue extractor. It performs no
sentiment analysis, inference, scoring, calibration, ranking, utility arithmetic,
causal estimation, or queue routing. Semantic assertions remain behind a separate
provider-neutral, human-validated boundary.

## Replay and provenance

An `AtomicIssueRecord` binds one issue-content revision to declared source-record
Expand Down Expand Up @@ -89,9 +134,13 @@ Human review remains necessary wherever source meaning, organizational values,
legal rights, or material consequences are in dispute. A candidate intervention
is a caller-supplied hypothesis, not evidence of an identified causal effect.

ISO/IEC 42001:2023 remains published as Edition 1. NIST reports that AI RMF 1.0
is under revision as of August 2026, so this module cites the current published
framework without assuming that its terminology or profiles are frozen.
ISO/IEC 42001:2023 remains published as Edition 1. ISO 8601-1:2019 and ISO
4217:2015 are the published standards used to describe the accepted date and
currency-code forms; later amendments, maintenance updates, or replacement
editions must be evaluated before changing the parser grammar or allowlists. NIST
reports that AI RMF 1.0 is under revision as of August 2026, so this module cites
the current published framework without assuming that its terminology or
profiles are frozen.

## References

Expand All @@ -100,10 +149,24 @@ P., & Roberts, K. (2024). *Artificial intelligence risk management framework:
Generative artificial intelligence profile* (NIST AI 600-1). National Institute
of Standards and Technology. https://doi.org/10.6028/NIST.AI.600-1

International Organization for Standardization. (2015). *Codes for the
representation of currencies* (ISO Standard No. 4217:2015).
https://www.iso.org/standard/64758.html

International Organization for Standardization. (2019). *Date and time—
Representations for information interchange—Part 1: Basic rules* (ISO Standard
No. 8601-1:2019). https://www.iso.org/standard/70907.html

International Organization for Standardization. (2023). *Information
technology—Artificial intelligence—Management system* (ISO/IEC Standard No.
42001:2023). https://www.iso.org/standard/81230.html

National Institute of Standards and Technology. (2023). *Artificial intelligence
risk management framework (AI RMF 1.0)* (NIST AI 100-1).
https://doi.org/10.6028/NIST.AI.100-1

Python Software Foundation. (2025). *Python 3.13 standard library: `datetime`,
`decimal`, `hashlib`, `re`, and `typing`*. https://docs.python.org/3.13/

The Unicode Consortium. (2025). *Unicode text segmentation* (Unicode Standard
Annex No. 29, Revision 47). https://www.unicode.org/reports/tr29/
136 changes: 136 additions & 0 deletions docs/superpowers/plans/2026-08-05-enterprise-explicit-value-parser.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
# Enterprise explicit-value parser implementation plan

## Goal

Advance issue #404 with the smallest reviewable parser slice after the governed
enterprise evidence and scoring-request contracts. Add a deterministic,
provider-neutral boundary for explicit values already present in authorized source
text. Do not perform semantic issue extraction, sentiment analysis, scoring,
calibration, ranking, utility arithmetic, causal inference, or queue routing.

## Accepted boundaries

The implementation belongs under `fast_mlsirm.scoring.enterprise_issue` and must
reuse `EnterpriseSourceRecord`, `EvidenceSpanRecord`,
`EnterpriseAssertionKind`, and the shared scoring contracts. It must not create a
parallel observation, result, engine, assessment, or rubric schema.

The parser receives source text transiently, verifies it against the exact
`EnterpriseSourceRecord` content fingerprint and character count, and returns
content-addressed records without retaining source text or clear-text customer
identifiers.

## Public contract

Add:

- `ExplicitValueKind`, with distinct values for `calendar_date`,
`deadline_date`, `money_amount`, `frequency_count`, and
`customer_identifier`;
- immutable `ExplicitValueRecord`, containing the exact source-record
fingerprint, UTF-8 source-span fingerprint, Python Unicode-code-point offsets,
kind-specific normalized payload, and parser-revision fingerprint;
- runtime-checkable `EnterpriseExplicitValueParser` protocol;
- `DeterministicExplicitValueParser`, whose parser revision is derived from its
patterns and configured ISO 4217 alphabetic currency-code allowlist;
- `parse_enterprise_explicit_values()` as the stable convenience boundary.

`ExplicitValueRecord.to_evidence_span()` must compile the exact span into the
accepted `EvidenceSpanRecord` boundary as a directly stated fact. This means only
that the value was explicitly present in the source, not that its real-world
content is true.

## Deterministic grammar

The first implementation recognizes only deliberately narrow, auditable forms:

1. Gregorian calendar dates in extended `YYYY-MM-DD` form, validated by
`date.fromisoformat()`;
2. deadlines expressed by an explicit marker such as `due`, `deadline`, `by`,
or `no later than`, followed by an accepted calendar date;
3. money amounts expressed as an allowlisted three-letter ISO 4217 alphabetic
code followed by an exact decimal amount; commas may be grouping separators,
and values are normalized through `Decimal` constructed from text;
4. frequencies such as `3 times per month`, `4 incidents per week`, or
`2 occurrences/year`, normalized to an integer count and one of `day`,
`week`, `month`, `quarter`, or `year`;
5. customer/account identifiers introduced by an explicit `customer_id`,
`customer id`, `account_id`, or `account id` label. The normalized payload
stores only SHA-256 over the identifier token, never the token itself.

Deadline matches take precedence over the embedded calendar-date match. Other
overlapping matches are rejected or deterministically resolved by documented
kind priority; the same source occurrence must never be multiplied silently.
Results are sorted by `(start_offset, end_offset, value_kind,
explicit_value_fingerprint)` and are independent of pattern declaration order.

## Fail-closed validation

Reject:

- non-`EnterpriseSourceRecord` inputs;
- non-string source text;
- source-content fingerprint or character-count mismatch;
- syntactically date-shaped but impossible Gregorian dates;
- malformed configured currency codes;
- non-finite or signed money amounts outside the accepted grammar;
- non-positive frequency counts;
- empty or oversized customer identifiers;
- overlapping accepted records that cannot be resolved by the declared deadline
precedence;
- record counts above the bounded parser limit;
- caller metadata containing raw/sensitive source fields.

All public identifiers must remain descriptive, nonnumeric, and at least two
snake-case tokens. Public docstrings and statement/branch coverage for added code
must be complete.

## Tests

Add deterministic tests for:

- exact extraction of all five kinds from one mixed Unicode source;
- source slices matching returned offsets while serialized records retain no raw
source text or customer token;
- deadline/date overlap producing one deadline record;
- parser output and fingerprints remaining invariant to configured currency-code
input order;
- exact decimal normalization without binary-float conversion;
- invalid date, source replay, source length, protocol, payload, overlap, and
maximum-record failures;
- conversion to the accepted `EvidenceSpanRecord` and shared
`EvidenceReference` role;
- no sentiment wording effect on extracted explicit values when the explicit
evidence is unchanged;
- 100% statement and branch coverage and complete public docstrings.

## Documentation and changelog

Extend `docs/enterprise_issue_evidence_contracts.md` with the transient-text,
code-point-offset, privacy, normalization, and interpretation boundaries. Add an
authoritative changelog fragment and render `CHANGELOG.md` only after the final
fragment is stable.

ISO 8601-1:2019 remains the current published basic-rules standard as of this
plan; ISO has an Edition 2 committee draft under development. ISO 4217:2015 is
the current published currency-code standard and is maintained through its
registration authority. Python regular-expression match spans are Unicode string
indices, not user-perceived grapheme-cluster positions; therefore the contract
must state its offset unit explicitly rather than imply UAX #29 grapheme
segmentation.

## References

International Organization for Standardization. (2015). *Codes for the
representation of currencies* (ISO Standard No. 4217:2015).
https://www.iso.org/standard/64758.html

International Organization for Standardization. (2019). *Date and time—
Representations for information interchange—Part 1: Basic rules* (ISO Standard
No. 8601-1:2019). https://www.iso.org/standard/70907.html

Python Software Foundation. (2025). *Python 3.13 standard library: `datetime`,
`decimal`, `hashlib`, `re`, and `typing`*. https://docs.python.org/3.13/

The Unicode Consortium. (2025). *Unicode text segmentation* (Unicode Standard
Annex No. 29, Revision 47). https://www.unicode.org/reports/tr29/
Loading
Loading