Repository navigation
docs(traceability): record item-delivery and result snapshot persist on main #96
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,8 @@ | ||
| # Requirements and Architecture Traceability | ||
|
|
||
| - Status: Normative traceability index | ||
| - Date: 2026-08-16 | ||
| - Evaluated protected-main implementation baseline: `62524a3efca319d6b624950d6f26db658f1e6ebb` | ||
|
Comment on lines
+4
to
+5
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
baseline="62524a3efca319d6b624950d6f26db658f1e6ebb"
git cat-file -e "${baseline}^{commit}"
paths=(
"src/item_delivery.rs"
"src/postgres_item_delivery.rs"
"src/response.rs"
"src/postgres_response_snapshot.rs"
"src/result.rs"
"src/postgres_result_snapshot.rs"
"src/postgres_consent.rs"
"src/postgres_data_rights.rs"
"src/postgres_health.rs"
"src/postgres_inbox_consumption.rs"
"src/postgres_instrument_release.rs"
"src/postgres_integration.rs"
"src/postgres_scoring_job.rs"
"src/postgres_scoring_request.rs"
"migrations/0001_integration_delivery.sql"
"migrations/0002_scoring_job_state.sql"
"migrations/0003_data_rights_propagation.sql"
"migrations/0004_item_delivery_evidence.sql"
"migrations/0005_consent_lifecycle.sql"
"migrations/0006_instrument_release.sql"
"migrations/0007_result_snapshot.sql"
"migrations/0010_response_snapshot.sql"
"migrations/0011_scoring_request.sql"
"migrations/0012_integration_consumption.sql"
"migrations/0015_data_rights_identity_verification.sql"
)
for path in "${paths[@]}"; do
git cat-file -e "${baseline}:${path}"
done
git show "${baseline}:tests/postgres_recovery_invariants.rs" |
rg -n 'claim_deadline_at'
git show "${baseline}:docs/TRACEABILITY.md" |
rg -n '62524a3efca319d6b624950d6f26db658f1e6ebb|postgres_item_delivery|postgres_response_snapshot|postgres_result_snapshot'Repository: ContextualWisdomLab/psychometrics-commons Length of output: 301 🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
baseline="62524a3efca319d6b624950d6f26db658f1e6ebb"
printf '%s\n' '--- baseline traceability references ---'
git show "${baseline}:docs/TRACEABILITY.md" |
nl -ba |
sed -n '1,145p' |
rg -n '62524a3efca319d6b624950d6f26db658f1e6ebb|postgres_item_delivery|postgres_response_snapshot|postgres_result_snapshot|Implemented|Active PR|Target'
printf '%s\n' '--- baseline test paths ---'
git ls-tree -r --name-only "${baseline}" -- tests |
sed -n '1,200p'
printf '%s\n' '--- claim_deadline_at references in baseline ---'
git grep -n 'claim_deadline_at' "${baseline}" -- ':!target' || true
printf '%s\n' '--- baseline path existence and object types ---'
paths=(
"src/item_delivery.rs"
"src/postgres_item_delivery.rs"
"src/response.rs"
"src/postgres_response_snapshot.rs"
"src/result.rs"
"src/postgres_result_snapshot.rs"
"src/postgres_consent.rs"
"src/postgres_data_rights.rs"
"src/postgres_health.rs"
"src/postgres_inbox_consumption.rs"
"src/postgres_instrument_release.rs"
"src/postgres_integration.rs"
"src/postgres_scoring_job.rs"
"src/postgres_scoring_request.rs"
"migrations/0001_integration_delivery.sql"
"migrations/0002_scoring_job_state.sql"
"migrations/0003_data_rights_propagation.sql"
"migrations/0004_item_delivery_evidence.sql"
"migrations/0005_consent_lifecycle.sql"
"migrations/0006_instrument_release.sql"
"migrations/0007_result_snapshot.sql"
"migrations/0010_response_snapshot.sql"
"migrations/0011_scoring_request.sql"
"migrations/0012_integration_consumption.sql"
"migrations/0015_data_rights_identity_verification.sql"
)
for path in "${paths[@]}"; do
printf '%s: ' "$path"
git cat-file -t "${baseline}:${path}"
doneRepository: ContextualWisdomLab/psychometrics-commons Length of output: 256 🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
baseline="62524a3efca319d6b624950d6f26db658f1e6ebb"
printf '%s\n' '--- baseline traceability references ---'
git show "${baseline}:docs/TRACEABILITY.md" |
sed -n '1,145p' |
grep -nE '62524a3efca319d6b624950d6f26db658f1e6ebb|postgres_item_delivery|postgres_response_snapshot|postgres_result_snapshot|Implemented|Active PR|Target' || true
printf '%s\n' '--- baseline test paths ---'
git ls-tree -r --name-only "${baseline}" -- tests |
sed -n '1,200p'
printf '%s\n' '--- claim_deadline_at references in baseline ---'
git grep -n 'claim_deadline_at' "${baseline}" -- ':!target' || true
printf '%s\n' '--- baseline path existence and object types ---'
paths=(
"src/item_delivery.rs"
"src/postgres_item_delivery.rs"
"src/response.rs"
"src/postgres_response_snapshot.rs"
"src/result.rs"
"src/postgres_result_snapshot.rs"
"src/postgres_consent.rs"
"src/postgres_data_rights.rs"
"src/postgres_health.rs"
"src/postgres_inbox_consumption.rs"
"src/postgres_instrument_release.rs"
"src/postgres_integration.rs"
"src/postgres_scoring_job.rs"
"src/postgres_scoring_request.rs"
"migrations/0001_integration_delivery.sql"
"migrations/0002_scoring_job_state.sql"
"migrations/0003_data_rights_propagation.sql"
"migrations/0004_item_delivery_evidence.sql"
"migrations/0005_consent_lifecycle.sql"
"migrations/0006_instrument_release.sql"
"migrations/0007_result_snapshot.sql"
"migrations/0010_response_snapshot.sql"
"migrations/0011_scoring_request.sql"
"migrations/0012_integration_consumption.sql"
"migrations/0015_data_rights_identity_verification.sql"
)
for path in "${paths[@]}"; do
printf '%s: ' "$path"
git cat-file -t "${baseline}:${path}"
doneRepository: ContextualWisdomLab/psychometrics-commons Length of output: 15989 🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
baseline="62524a3efca319d6b624950d6f26db658f1e6ebb"
printf '%s\n' '--- traceability lines 55-65 ---'
git show "${baseline}:docs/TRACEABILITY.md" |
sed -n '55,65p'
printf '%s\n' '--- traceability lines 88-95 ---'
git show "${baseline}:docs/TRACEABILITY.md" |
sed -n '88,95p'
printf '%s\n' '--- traceability lines 105-140 ---'
git show "${baseline}:docs/TRACEABILITY.md" |
sed -n '105,140p'
printf '%s\n' '--- recovery-related baseline tests ---'
for path in \
tests/postgres_scoring_job_lease_expiry_recovery.rs \
tests/postgres_scoring_job_classification_locking.rs \
tests/postgres_scoring_job_persistence.rs \
tests/postgres_scoring_job_transaction_contract.rs \
tests/postgres_scoring_job_terminal_outcomes.rs
do
if git cat-file -e "${baseline}:${path}"; then
printf '%s\n' "--- ${path} ---"
git show "${baseline}:${path}" |
grep -nE 'claim|lease|recover|expiry|FOR UPDATE|terminal' || true
else
printf '%s\n' "MISSING: ${path}"
fi
done
printf '%s\n' '--- baseline references to recovery invariant test names ---'
git grep -nE 'recovery_invariants|lease_expiry_recovery|claim_deadline_at' "${baseline}" -- . || trueRepository: ContextualWisdomLab/psychometrics-commons Length of output: 17249 🏁 Script executed: #!/usr/bin/env bash
set -euo pipefail
baseline="62524a3efca319d6b624950d6f26db658f1e6ebb"
source_map_sha="085ef4b4714796a77fd4645eeb46b028f95929fc"
printf '%s\n' '--- exact baseline declaration lines ---'
git show "${baseline}:docs/TRACEABILITY.md" |
awk 'NR <= 6 { print NR ":" $0 }'
printf '%s\n' '--- exact source-map baseline line ---'
git show "${baseline}:docs/TRACEABILITY.md" |
awk 'NR >= 88 && NR <= 95 { print NR ":" $0 }'
printf '%s\n' '--- source-map SHA object type ---'
git cat-file -t "${source_map_sha}^{commit}"
printf '%s\n' '--- baseline recovery test path ---'
git cat-file -e "${baseline}:tests/postgres_scoring_job_lease_expiry_recovery.rs"Repository: ContextualWisdomLab/psychometrics-commons Length of output: 922
🤖 Prompt for AI AgentsSource: Coding guidelines
Contributor
There was a problem hiding this comment. This SHA is not the tree this PR will land. |
||
|
|
||
| This document prevents product requirements, architecture decisions, governance, code, and release evidence from drifting independently. It is intentionally explicit about what is **implemented on the evaluated protected-main baseline**, what exists only on an **active PR**, and what remains **target architecture**. | ||
|
|
||
|
|
@@ -22,12 +22,12 @@ An active PR, architecture document, conversation decision, or scheduler plan is | |
| |---|---|---|---|---| | ||
| | Anonymous core assessment | PRD §3.1, §9.1 | TRD §5, §10; UML anonymous sequence | ADR-0002, ADR-0003, ADR-0005 | Session lifecycle primitives implemented, including creation bound to one published locale-specific release; anonymous credential/HTTP flow is Target | | ||
| | Pause/resume | PRD §3.1, §9.1 | TRD §5 | ADR-0005 | **Implemented** in `src/session.rs` with fail-closed transitions | | ||
| | Sequence-aware item delivery evidence | PRD §3.1, §9 | TRD §5–7 | ADR-0005, ADR-0010 | **Implemented** domain primitive in `src/item_delivery.rs` plus `migrations/0004_item_delivery_evidence.sql` and `src/postgres_item_delivery.rs`; API delivery orchestration remains Target | | ||
| | Idempotent response events | PRD §9.2 | TRD §6 | ADR-0005, ADR-0010 | **Implemented** in `src/response.rs` with canonical SHA-256 payload-digest identity; persistence adapter is Target | | ||
| | Immutable response snapshot before scoring | PRD §9.3 | TRD §5–8 | ADR-0005, ADR-0010 | **Implemented** domain semantics in `src/response.rs` plus `migrations/0010_response_snapshot.sql` and `src/postgres_response_snapshot.rs` | | ||
| | Version-pinned scoring | PRD §9.4, §10 | TRD §8 | ADR-0004, ADR-0010 | **Implemented** reusable product-side scoring dispatch contract in `src/scoring.rs` with canonical SHA-256 engine-artifact digest provenance plus `migrations/0011_scoring_request.sql` / `src/postgres_scoring_request.rs` request-identity persistence; live fast-mlsirm integration is Target | | ||
| | Bounded asynchronous scoring retry/quarantine with stale-worker fencing | PRD §9.4, §10 | TRD §8; ADR-0015 transaction boundary | ADR-0004, ADR-0010, ADR-0015 | **Implemented** product lifecycle plus PostgreSQL enqueue, claim, retry, completion, expiry recovery, and cancellation without transferring a fence; live fast-mlsirm execution remains Target | | ||
| | Immutable result provenance | PRD §3.1, §9.4 | TRD §9 | ADR-0004, ADR-0010 | **Implemented** in `src/result.rs` plus `migrations/0007_result_snapshot.sql` and `src/postgres_result_snapshot.rs`; result-serving transport remains Target | | ||
| | Deterministic narrative fallback | PRD §3.2, §9.5 | TRD §17; Architecture narrative view | ADR-0009, ADR-0010, ADR-0018 | Target | | ||
|
Contributor
There was a problem hiding this comment. This row is still Target, but |
||
| | Continuous scores remain source of truth; Personality Style is presentation | PRD §3.2 | Measurement Governance; AI Governance | ADR-0018 | Target product narrative mapping; numeric source remains External fast-mlsirm contract | | ||
| | Immutable instrument release/version lifecycle | PRD §6, §9 | TRD §7; UML publication state | ADR-0005, ADR-0010 | **Implemented** in `src/instrument.rs` plus `migrations/0006_instrument_release.sql` and `src/postgres_instrument_release.rs`: immutable release manifest, exact version/digest/locale/item set, fail-closed Draft/Review/Published/Suspended/Retired lifecycle, idempotent publication events, and new-session eligibility | | ||
|
|
@@ -54,13 +54,13 @@ An active PR, architecture document, conversation decision, or scheduler plan is | |
| |---|---|---|---| | ||
| | Server-authoritative session state | TRD §5 | `src/session.rs` + session contract tests, including published-release/locale binding at creation | persistence/API concurrency test | | ||
| | Only Active accepts responses | TRD §5–6 | `SessionState::accepts_responses` + response tests | transport-level rejection test | | ||
| | Item delivery sequence is positive and evidence-safe | TRD §5–7 | `src/item_delivery.rs` + `src/postgres_item_delivery.rs` persist exact delivery events | API delivery orchestration | | ||
| | Conflicting idempotency replay fails closed | TRD §6 | `src/response.rs` | DB uniqueness/concurrency test | | ||
| | Snapshot requires Completed state | TRD §5–6 | `src/response.rs` | transaction atomicity test with persistence | | ||
| | Scoring uses durable snapshot identity | TRD §8 | `src/scoring.rs` requires a canonical SHA-256 engine-artifact digest | live adapter + retry/outbox integration | | ||
| | Stale scoring worker cannot complete a newer attempt | TRD §8; ADR-0015 | `src/scoring_job.rs` uses monotonically increasing fencing tokens and rejects stale/expired completion or failure evidence; `src/postgres_scoring_job.rs` persists enqueue, claim, retry, terminal outcomes, expired-lease recovery, and cancellation without transferring a fence | live adapter evidence | | ||
| | Scientific failure is typed, no invented score | TRD §8; Measurement Governance | scoring contract tests | cross-process failure injection | | ||
| | Historical result does not mutate | TRD §9 | `src/result.rs` plus `src/postgres_result_snapshot.rs` immutable snapshot persistence | API supersession tests | | ||
| | Narrative cannot mutate score / deterministic fallback exists | AI Governance; ADR-0018 | architecture policy | mapping implementation + canonical style-assignment key + fallback/no-score-mutation tests | | ||
| | Instrument release bytes/version/item order are immutable | TRD §7 | `src/instrument.rs` + publication contract tests; `src/postgres_instrument_release.rs` persists immutable manifest columns | API publication integration | | ||
| | Only Published release accepts new sessions | TRD §7 | `PublicationState::accepts_new_sessions` in `src/instrument.rs`; `AssessmentSession` creation copies exact published release/version/locale provenance and fails closed on unpublished eligibility or locale mismatch | session-creation persistence/API integration test | | ||
|
|
@@ -73,7 +73,7 @@ An active PR, architecture document, conversation decision, or scheduler plan is | |
| | Export/deletion requires request-specific identity verification | TRD §13 | `src/data_rights.rs`; `src/postgres_data_rights.rs` persists the requested identity and local propagation events | Keyverse/account/anonymous transport integration | | ||
| | Legal retention represented explicitly | TRD §13 | `src/data_rights.rs` partial completion | dependency execution/restore tests after local propagation | | ||
| | No cross-service DB access | TRD §1–2; ADR-0015 | architecture policy only | deployment credential/fitness-function test | | ||
| | Initial physical persistence target is upstream PostgreSQL 18.x | ADR-0015; Deployment/Operations | **Implemented subset** in `migrations/0001_integration_delivery.sql`, `migrations/0002_scoring_job_state.sql`, `migrations/0003_data_rights_propagation.sql`, `migrations/0004_item_delivery_evidence.sql`, `migrations/0005_consent_lifecycle.sql`, `migrations/0006_instrument_release.sql`, `migrations/0007_result_snapshot.sql`, `migrations/0010_response_snapshot.sql`, `migrations/0011_scoring_request.sql`, `migrations/0012_integration_consumption.sql`, `migrations/0015_data_rights_identity_verification.sql`, matching adapters, and PostgreSQL operational-store readiness | remaining product aggregates, crash/restart restore acceptance | | ||
| | No default tenant for writes | TRD §11; Security/Data | authorization-domain primitive exists; persistence remains Target | persistence/API tenant negative tests | | ||
| | Tenant-bound transactional outbox/inbox | TRD §19–20; ADR-0014/0015 | `src/integration.rs` domain envelope/inbox/retry contracts plus PostgreSQL tenant/source-scoped integration evidence, delivery-attempt persistence, and inbox consumption | durable side-effect processing completion, poison-message/crash recovery, broader aggregate transaction integration | | ||
| | Inbox receipt is not side-effect completion | ADR-0014/0015; UML integration sequence | `src/integration.rs` states/retry semantics; PostgreSQL inbox consumption persists pending/processing/completed and expire-and-reclaim | live adapter crash/retry tests | | ||
|
|
@@ -89,7 +89,7 @@ An active PR, architecture document, conversation decision, or scheduler plan is | |
|
|
||
| ## 4. Source module map | ||
|
|
||
| Current protected-main Rust module surface on `62524a3efca319d6b624950d6f26db658f1e6ebb`: | ||
|
|
||
| ```text | ||
| src/lib.rs | ||
|
|
@@ -108,6 +108,9 @@ src/lib.rs | |
| ├── postgres_inbox_consumption.rs # PostgreSQL inbox consumption distinct from receipt | ||
| ├── postgres_instrument_release.rs # PostgreSQL locale-specific instrument-release persistence | ||
| ├── postgres_integration.rs # PostgreSQL integration evidence/delivery-attempt persistence adapter | ||
| ├── postgres_item_delivery.rs # PostgreSQL sequence-aware item-delivery event persistence | ||
| ├── postgres_response_snapshot.rs # PostgreSQL immutable completed-session response snapshots | ||
| ├── postgres_result_snapshot.rs # PostgreSQL immutable result-snapshot persistence | ||
| ├── postgres_scoring_job.rs # PostgreSQL scoring enqueue/claim/retry/cancel/terminal persistence | ||
| ├── postgres_scoring_request.rs # PostgreSQL version-pinned scoring-request identity | ||
| ├── reference.rs # internal opaque-reference normalization | ||
|
|
@@ -122,17 +125,21 @@ migrations/ | |
| ├── 0001_integration_delivery.sql | ||
| ├── 0002_scoring_job_state.sql | ||
| ├── 0003_data_rights_propagation.sql | ||
| ├── 0004_item_delivery_evidence.sql | ||
| ├── 0005_consent_lifecycle.sql | ||
| ├── 0006_instrument_release.sql | ||
| ├── 0007_result_snapshot.sql | ||
| ├── 0010_response_snapshot.sql | ||
| ├── 0011_scoring_request.sql | ||
| ├── 0012_integration_consumption.sql | ||
| └── 0015_data_rights_identity_verification.sql | ||
| ``` | ||
|
|
||
| Still-Target logical modules/adapters include remaining product aggregate persistence/repositories, public/admin HTTP and event transports, live fast-mlsirm/Keyverse/Gyeot/TEPP/semantic-data-portal adapters, research-release staging, deterministic narrative mapping, longitudinal normalized ingestion, participant identity-link history persistence, runtime health transports/metrics, and Measurement Workbench orchestration. | ||
|
|
||
| ### Active implementation work that is not protected-main truth | ||
|
|
||
| **Active PR** remaining PostgreSQL persist and operator-health HTTP slices are not protected-main truth until unchanged reviewed/check-clean heads are integrated. This baseline records item-delivery ledger persistence (#48) and immutable result snapshots (#51). Session, identity-link, response-event, scoring-completion, research, data-rights completion, and HTTP health-probe work remain Active PR only. Merged #76 processing-start is current-main history after this evaluated SHA, not Active PR and not this baseline's claimed surface. | ||
|
Comment on lines
140
to
+142
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Line 142는 As per coding guidelines: “traceability must separate current implementation from targets” 규칙에 따라, 구현된 primitive과 미완료 layer의 상태를 분리해야 합니다. 🤖 Prompt for AI AgentsSource: Coding guidelines
Contributor
There was a problem hiding this comment. The Active PR note only carves out #76 as later-than-baseline history. It does not mention #73 deterministic narrative, #85 dual-proof linking, #68 atomic scoring-dispatch persist, #81 claim-expiry, or #72 recovery invariants, all of which are already on |
||
|
|
||
| ## 5. ADR traceability by concern | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This entry records the documentation intent but not the actual code change that unblocked exact-head CI: seeding
claim_deadline_aton the processing restore fixture. If this PR remains the recovery fix vehicle, the changelog must say that a restored processing claim keeps its database-authoritative deadline.