DOC73_V1_6_HELPER_HOMES_R0.2.md
Current Specs/DOC73/DOC73 Helper Home and Deferral List/DOC73_V1_6_HELPER_HOMES_R0.2.md
ELNOR REPO READER TEXT MIRROR
Original path: Current Specs/DOC73/DOC73 Helper Home and Deferral List/DOC73_V1_6_HELPER_HOMES_R0.2.md
Source repo: /Users/OpenClaw1/Elnor/Elnor Specs
Git branch: main
Git commit: dbaa25962edc11ab30e8d4ca1715f9ae5bf77331
Generated: 2026-06-09T01:23:58.539Z
---
# DOC73 V1.6 Release Wave — Helper Function Homes Appendix R0.2
**Document kind:** Cross-artifact appendix to V1.6 release wave (companion to Artifacts 1 R0.5, 2 R0.4, 3 R0.3, 4 R0.4, 5 R0.3).
**Audit date origin:** 2026-05-03 (Step 9 cross-artifact audit XCRIT-1).
**Author:** Claude (Step 9 deliverable per architect Path B-minus).
**Status:** R0.2 — CSA extraction applied; §1.26 lookup_csa_injection_tier_policy REMOVED; pending red-team Round 1.
**R0.2 changes from R0.1 (per architect CSA extraction prompt 2026-05-04):**
- §1.26 `lookup_csa_injection_tier_policy` declaration REMOVED (CSAInjectionTierPolicy was deleted from Artifact 4 R0.4 §18 per CSA extraction; helper is no longer needed)
- §1.27 `lookup_latest_rollup` PRESERVED (still used by Artifact 2 §25 RecentActivityRollup consumer; not CSA-specific)
- §6.F coverage table "§18 CSA" mention reframed to "§18 session-orientation deferred"
- All other helper declarations PRESERVED (no CSA dependency)
**Companion docs:** AUDIT_CROSS_ARTIFACT_R0.1.md (XCRIT-1 source); DOC73_V1_6_CSA_EXTRACTION_PRE_REPORT.md + DOC73_V1_6_CSA_EXTRACTION_REPORT.md (R0.2 extraction); AUDIT_DOC73_Artifact2_R0.1.md (CRIT-A2-2); AUDIT_DOC73_Artifact4_R0.1.md (HIGH-A4-1); AUDIT_DOC73_Artifact5_R0.1.md (MED-A5-5); DOC73_V1_6_INVENTORY_ADJUDICATION_CARD_V4 (1) copy.md (V4 §0.4 owner-doc adapter mapping).
---
## §0. Purpose, scope, and conformance
### §0.1 Purpose
Across the V1.6 release wave (5 artifacts, ~27,467 lines), pseudocode and runtime specs reference **~82 helper functions** that are not declared with canonical signatures. Per AUDIT_CROSS_ARTIFACT_R0.1.md XCRIT-1, these phantom helpers were systematically deferred from per-artifact audits to a Step 9 cross-artifact consolidation deliverable (this document).
Without a canonical helper-home appendix, coding agents implementing each artifact would (a) invent helpers locally with subtly different signatures, (b) duplicate helpers across artifacts under varying names, OR (c) miss helpers entirely. Cross-implementation drift is inevitable.
This document declares for each phantom helper:
1. **Helper signature** (TypeScript-style; parameter types and return type).
2. **Owner home** (per V4 §0.4 owner-doc adapter mapping — typically: EC database access layer for `lookup_*` and `persist_*`; DOC25 V2.0+ for ingestion-side `sniff_*`, `attempt_strip_*`; DOC72 R5.74+ for graph queries; DOC10 / Artifact 4 UI layer for `emit_user_notification`; PropA cross-doc for `check_propa_authorization`).
3. **Caller artifacts** (which V1.6 artifacts and sections invoke the helper).
4. **Behavioral contract** (when called, what it returns, error modes, retention class, durability discipline).
5. **V1.6 implementation guidance** (notes for coding agents).
### §0.2 Scope — which helpers are in this appendix
In scope:
- All ~82 phantom helpers enumerated in AUDIT_CROSS_ARTIFACT_R0.1.md XCRIT-1.
- Helpers whose **signature** is referenced in V1.6 release wave pseudocode but whose **canonical home** is not yet declared.
Out of scope (NOT in this appendix; canonical home declared elsewhere):
- `kernel.submit_operation` (Artifact 3 §1.4 canonical).
- `kernel.read_envelope` / `kernel.record_extraction_state_transition` / `kernel.record_*_receipt` (Artifact 3 §1.4 + §16 canonical).
- Schema constructors (e.g., `new SourceArtifact(...)` — schema declared in Artifact 5 §2.2; constructor implicit).
- ID-generation primitives (`new_id()`, `new_operation_id()` — Artifact 1 §A.1 declared).
- Time primitives (`NOW()` — Artifact 1 §19.1 INV-V16-TIMEZONE-1 canonical).
- Hash primitives (`hash_random_token()`, `hash_content(...)` — Artifact 1 §A.9 ContentHashRef family + Artifact 5 §10 multi-hash discipline).
- Direct DB primitives (`db.read_*`, `db.list_*`, `db.write_*` — EC database access layer infrastructure; not enumerated as separate helpers).
### §0.3 Categorization (per AUDIT_CROSS_ARTIFACT_R0.1.md XCRIT-1)
The ~82 phantom helpers split into 6 categories by ownership and behavior:
```text
Category Count Owner home Section
────────────────────────────────────────────────────────────────────────────────────
DB-layer lookups ~25 EC database access layer §1
Pure functions ~15 Inline declarations per artifact §2
(no canonical home file; logic is small)
Persistence helpers ~12 EC persistence runtime §3
(per V3.7 OBL-EC-NEW-* row family)
Notification/event ~8 DOC10 / Artifact 4 UI layer §4
(Q Dashboard surfacing)
Cross-doc lookups ~10 cross-doc per V4 §0.4 §5
(PropA / DOC10 / DOC72 / DOC25)
Specialized ~25+ split per artifact + EC kernel runtime §6
(kernel orchestration + binding fire +
search router + simulation + replay)
```
Per-artifact distribution of phantom helper references:
```text
Artifact Approx phantom helper references (R0.2) Audit finding
────────────────────────────────────────────────────────────────────────
Artifact 1 ~0 (canonical schema home; helpers — (no per-artifact
consumed not produced) finding)
Artifact 2 ~28 (Group J/O/K runtime) CRIT-A2-2
Artifact 3 ~12 (kernel orchestration; mostly — (mostly
inline-declared) contained)
Artifact 4 ~32 (search router + share-link + HIGH-A4-1
capability registry + access overlay)
Artifact 5 ~22 (extraction FSM + hash collision + MED-A5-5
caching tier)
────────────────────────────────────────────────────────────────────────
TOTAL ~82 (unique helpers; some referenced from multiple artifacts)
```
### §0.4 V4 §0.4 owner-doc adapter mapping — the rule
Per V4 §0.4 (owner-doc adapter mapping; lines 916-1042):
```text
EC Core Addendum A V3.5+:
- PrimaryPBEOrchestrator runtime (sole writer per INV-15.7.8).
- Database access layer (lookup_*, list_*).
- Persistence runtime (persist_*).
- Capacity lease lifecycle (estimate_capacity_cost).
- Ephemeral session_context store (per V3.7 OBL-EC-NEW-SESSION-CONTEXT-01).
- Content-addressable blob store (per V3.7 OBL-EC-NEW-BLOB-STORE-01).
DOC25 V2.0+ (per Artifact 5 §1.2 amendments A1-A9):
- Ingestion-side primitives (sniff_*, attempt_strip_*, decompression checks).
- Multi-hash discipline (compute_intersection_across_kinds, classify_collision_severity).
DOC72 R5.74+:
- Graph queries (lookup_target_node_kind for world_entity / work_product
type lookup).
- WorkContextConstellation lookups (per Artifact 1 §15.X.7.7-9 + §16
Mechanism 4 cross-references).
- Filing-relationship edge queries (cross-Artifact 2 §15).
- Source-kind registry (per OBL-D72-V16-K-SOURCE-REGISTRY-01).
DOC24 R3.1+:
- Capability registry (register_capability_atomically; lookup_capability_policy).
- Reason-code namespace (lookup_reason_code; resolve_recipient_visibility).
- Search router runtime (dispatch_executor; spawn_specialist_sub_agent).
- Retention policy / corpus reconciliation.
DOC10 / Q Dashboard UI layer (Artifact 4-side):
- Notification surfacing (emit_user_notification, emit_user_warning).
- Recall request UI (emit_recall_request_to_recipient).
- Audit log surfacing (emit_audit_log_entry).
- Field extraction conflict surfacing (emit_field_extraction_conflict).
PropA R7+ (cross-doc per V4 §3.7):
- PropA authorization checks (check_propa_authorization).
- Active-for-document checks (propa_authorization_active_for).
V1.6 Release wave (Artifacts 1-5; co-located with caller):
- Pure functions (most_restrictive_*, lowest_in_lattice, intersect_*,
matches_pattern, classify_*).
- Specialized orchestration helpers (fire_with_*, dispatch_binding_fire_*,
construct_compensating_envelope, apply_inverse_effect).
```
### §0.5 Conformance check (R1.0 freeze gate)
For coding agents implementing V1.6, the following conformance check applies:
```text
PRE-IMPLEMENTATION CHECKLIST:
□ Every helper referenced in an artifact's pseudocode has a canonical
home declaration in this appendix (or in the artifact itself).
□ Coding agents implementing artifact X read this appendix BEFORE
writing code that calls a helper not declared in artifact X itself.
□ Implementation matches the helper signature and behavioral contract
EXACTLY; deviation requires audit-log entry and architect approval.
□ DB-layer helpers (§1) are implemented in the EC database access
layer; consumers in V1.6 artifacts call them but do NOT redeclare.
□ Pure functions (§2) MAY be inlined per artifact (each artifact
declares its own inline copy with identical signature).
□ Persistence helpers (§3) are implemented in EC persistence runtime;
consumers call them but do NOT redeclare.
□ Notification/event helpers (§4) are implemented in DOC10 / Artifact
4 UI layer; consumers call them via well-defined message-bus or
direct UI dispatch.
□ Cross-doc helpers (§5) are implemented in upstream docs; V1.6
artifacts consume via cross-doc interface contracts.
□ Specialized helpers (§6) are implemented co-located with caller
OR in EC kernel runtime; per-helper home in §6 entries.
POST-IMPLEMENTATION CHECKLIST:
□ No helper has TWO canonical implementations (one per artifact);
cross-implementation drift = INV-V16-NO-LOCAL-SCHEMA-1 violation.
□ Helper signatures in implementations match this appendix
EXACTLY (per parameter type, return type).
□ Behavioral contracts in implementations honor retention class,
durability discipline, and error modes per appendix entries.
□ Audit log surfaces every cross-doc helper call with the cross-doc
interface contract metadata (per V3.7 OBL-EC-NEW-* row family).
```
### §0.6 V1.6 release wave handoff package
This document is part of the V1.6 release wave handoff package that ships at R1.0 freeze. The package includes:
- DOC73_Artifact1_R0.4.md (Core; absorbs Ref types from Artifact 2 R0.2 §0.7 per XHIGH-2)
- DOC73_Artifact2_R0.3.md (Legal & Corpus Surfaces; adds compute_engagement_rate formula per XHIGH-4)
- DOC73_Artifact3_R0.2.md (EC + DOC73 Transaction Kernel; no R0.3 changes)
- DOC73_Artifact4_R0.2.md (DOC24 + EC Session & Search Runtime; no R0.3 changes)
- DOC73_Artifact5_R0.3.md (DOC25 Legal Artifact & Materialization; adds ECFHeaderParserOutput.ecf_annotations field per XHIGH-3)
- DOC73_V1_6_HELPER_HOMES_R0.1.md (this document)
- DOC73_V1_6_BUILD_QUESTIONS.md (47 Tier B architect-decision items)
- DOC73_V1_6_DEFERRAL_INVENTORY_R1.md (V1.6.1 / V1.7+ deferrals)
- AUDIT_CROSS_ARTIFACT_R0.1.md (Step 9 cross-artifact audit)
- All five per-artifact audits (AUDIT_DOC73_Artifact{1,2,3,4,5}_R0.1.md)
R1.0 freeze proceeds when:
- All R0.3 patches applied (Artifacts 1 R0.4, 2 R0.3, 5 R0.3).
- This appendix R0.1 ships.
- Architect Will completes triage of 47 Tier B BUILD_QUESTIONS items.
- Cross-artifact worked examples (per XHIGH-1) added to Artifact 1 R0.4 §B.
---
## §1. DB-layer lookup helpers (~25 helpers)
Owner home: **EC database access layer** (per Artifact 1 §3 calibration table forecast: EC Core Addendum A V3.5+).
These are read-only graph / row queries against the ELNOR knowledge graph, durable receipt store, blob store, and corpus_membership_records table. Implementations live in EC Core Addendum A V3.5+ database access layer; V1.6 release wave artifacts consume via well-defined function signatures.
Common conformance rules for §1 helpers:
- Read-only; no side effects.
- Return `undefined` (or empty array) when no match; never throw on miss.
- Honor caller's session_context (per V3.7 OBL-EC-NEW-SESSION-CONTEXT-01) for query scoping.
- Honor INV-B2-OVERLAY-RESOLUTION-1 access overlays at lookup boundary (overlay enforcement is at READ time; per Artifact 4 §16 + Artifact 3 §12).
- Honor policy_generation_id when caller supplies it (per V4-K-INV-DEDUP-3 lazy re-evaluation).
- All helpers are deterministic for a given EC state snapshot.
- Performance class: indexed lookup (O(log N) or O(1)); coding agents MUST NOT implement full-table scans.
### §1.1 `lookup_topic_visibility_policy(visibility_policy_ref: string): TopicVisibilityPolicy | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §5.2 `filter_topics_by_share_link_visibility`.
**Returns:** TopicVisibilityPolicy schema (per Artifact 2 §5.1) or undefined on miss.
**Behavior:** Looks up the named TopicVisibilityPolicy by its ref. Pure read; no side effects.
**Retention class:** policy is durable (per Artifact 2 §5.1).
**Error modes:** undefined on missing ref; never throws.
**Implementation note:** Backed by a TopicVisibilityPolicy table indexed on `policy_id`.
### §1.2 `lookup_pattern_library_visibility(visibility_policy_ref: string): PatternLibraryVisibility | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §6.2 `filter_pattern_library_for_session`.
**Returns:** PatternLibraryVisibility schema (per Artifact 2 §6.1) or undefined on miss.
**Behavior:** Looks up the named PatternLibraryVisibility policy. Pure read.
**Retention class:** policy is durable.
**Error modes:** undefined on missing ref.
**Implementation note:** Backed by a PatternLibraryVisibility table indexed on `policy_id`.
### §1.3 `lookup_corpus_profile(corpus_profile_ref: string): CorpusProfile | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §9.3 `fork_corpus_profile`; multiple read paths in Artifact 4 §15.4 (search router scope resolution).
**Returns:** CorpusProfile schema (per Artifact 2 §3.1) or undefined.
**Behavior:** Looks up canonical CorpusProfile for the given world_entity ref or work_product ref (per V4-O-1 entity_subtype split).
**Retention class:** corpus profiles are durable.
**Error modes:** undefined on missing ref.
**Implementation note:** Backed by corpus_profiles table indexed on `corpus_profile_id`. May resolve aliases via CorpusProfileFork lineage (per Artifact 2 §9).
### §1.4 `lookup_resolved_case_identity(case_ref: CaseRef): ResolvedCaseIdentity | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §11.7 `resolve_case_scope`.
**Returns:** ResolvedCaseIdentity schema (per Artifact 2 §11.3) or undefined.
**Behavior:** Looks up case identity record, including consolidation/transfer/severance history per V4-O-3.
**Retention class:** durable; case-identity records persist for matter lifetime.
**Error modes:** undefined on missing ref.
**Implementation note:** Backed by resolved_case_identity table indexed on `case_id` and on `alternate_case_numbers[]`.
### §1.5 `lookup_filing_units_by_exact_case_number(case_number: string): FilingUnit[]`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §11.7 `resolve_case_scope` (exact-match path).
**Returns:** array of FilingUnits whose `case_number` field matches exactly (case-insensitive normalized form).
**Behavior:** Pure read; returns empty array if no FilingUnits match.
**Retention class:** durable.
**Error modes:** never throws; empty array on no match.
**Implementation note:** Backed by FilingUnit table with index on canonicalized `case_number`. Consumers MUST NOT pre-normalize the input; the helper applies canonical normalization internally.
### §1.6 `lookup_filing_units_by_any_case_number(all_case_numbers: string[]): FilingUnit[]`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §11.7 `resolve_case_scope` (consolidated/transferred case path).
**Returns:** array of FilingUnits whose `case_number` matches any of the supplied alternate case numbers (per ResolvedCaseIdentity.alternate_case_numbers).
**Behavior:** Pure read; computes union over alternate case numbers.
**Retention class:** durable.
**Error modes:** never throws; empty array on no match.
**Implementation note:** Backed by same index as §1.5; performs IN clause on alternate_case_numbers.
### §1.7 `lookup_by_canonical_key(identity: FilingUnitIdentity): FilingUnit | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §11.5 `lookup_or_create_filing_unit`; Artifact 2 §11.5.X `resolve_filing_unit_for_new_artifact` (HIGH-A2-3 decision tree).
**Returns:** FilingUnit matching the canonical identity tuple (court_id + case_number + docket_entry_no + filing_kind + filing_party + filing_date), or undefined.
**Behavior:** Canonical-key match per V3-O-1 + V4-O-2. Returns the *current* FilingUnit (not a specific FilingUnitVersion).
**Retention class:** durable.
**Error modes:** undefined on no match; throws `incomplete_canonical_key` if `canonical_key_complete(identity)` is false.
**Implementation note:** Backed by FilingUnit table with composite index on canonical-key tuple. The helper is the canonical entry point for FilingUnit identity resolution; consumers MUST use it rather than re-implementing canonical-key matching.
### §1.8 `lookup_or_create_filing_unit(candidate_identity: FilingUnitIdentity): FilingUnit`
**Owner:** EC database access layer (with kernel envelope for create branch).
**Caller:** Artifact 2 §11.5.
**Returns:** FilingUnit (existing or newly created).
**Behavior:** If `canonical_key_complete(candidate_identity)`, calls §1.7 first; if existing returns it. Otherwise creates a new FilingUnit (constructs kernel envelope per Artifact 3 §4.3.1 effect_kind=node_create) and returns the freshly created FilingUnit.
**Retention class:** durable.
**Error modes:** throws `incomplete_canonical_key` if identity is insufficient; throws `kernel_submission_failed` on envelope rejection.
**Implementation note:** This is a hybrid lookup-or-create helper; the create branch goes through PrimaryPBEOrchestrator.submit_operation (per INV-15.7.8 sole-writer). Coding agents MUST NOT bypass the kernel for the create branch.
### §1.9 `lookup_target_node_kind(node_ref: string): NodeKind | "node_not_found"`
**Owner:** EC database access layer (DOC72 graph type lookup).
**Caller:** Artifact 2 §3.2 `validate_corpus_profile_storage` (INV-J-PROFILE-1 envelope-validation layer per MED-A2-4 R0.2 fix).
**Returns:** the canonical node_kind (per DOC72 R5.74+ NodeKind enum: world_entity, work_product, derived_memory, raw_data_node, etc.) or `"node_not_found"`.
**Behavior:** Pure DOC72 graph type lookup; no overlay enforcement (validation-layer check, not query-layer).
**Retention class:** durable; node_kind is set at create time and immutable.
**Error modes:** returns `"node_not_found"` rather than throwing (consumer treats as validation failure).
**Implementation note:** Backed by DOC72 R5.74+ graph index; per V4-§0.4-1 DOC72 owns NodeKind taxonomy. This helper is a thin adapter over `db.read_graph_node(ref).node_kind`.
### §1.10 `lookup_overlays_at_part_granularity(part: FilingPart): AccessOverlay[]`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §11.4.X `check_filing_part_visibility` (INV-O-FILING-PART-VIS-1 read-time runtime check per HIGH-A2-1 R0.2 fix).
**Returns:** array of AccessOverlay records that target this filing-part granularity (per V4-B2-1 INV-B2-OVERLAY-RESOLUTION-1).
**Behavior:** Pure read of access_overlays table filtered to overlays whose `target_kind = "filing_part"` and `target_ref = part.id`.
**Retention class:** durable.
**Error modes:** empty array on no overlays; never throws.
**Implementation note:** Backed by access_overlays table with index on `(target_kind, target_ref)`.
### §1.11 `lookup_filing_part_text_hash(filing_unit_ref: FilingUnitRef, filing_unit_version_ref: FilingUnitVersionRef): ContentHashRef[]`
**Owner:** EC database access layer.
**Caller:** Artifact 5 §6.5 `classify_cross_version_sharing`.
**Returns:** array of segment_text_hashes for all ArtifactSegments mapped to this FilingUnit at this FilingUnitVersion. Order: ArtifactSegment.page_range ascending.
**Behavior:** Per CRIT-A5-3 R0.2 fix: filing-part = ArtifactSegment. Helper aggregates segment_text_hash across all ArtifactSegments belonging to the FilingUnitVersion.
**Retention class:** durable (segment hashes never change for a given segment).
**Error modes:** empty array if no segments mapped; never throws.
**Implementation note:** Backed by ArtifactSegment table with composite index on `(filing_unit_ref, filing_unit_version_ref)`. Per Artifact 5 §6.5 declared signature.
### §1.12 `lookup_filing_part_text_hash_at_segment(filing_unit_ref: FilingUnitRef, filing_unit_version_ref: FilingUnitVersionRef, segment_id: string): ContentHashRef | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 5 §6.5.
**Returns:** segment_text_hash for the specific ArtifactSegment, or undefined if segment is not mapped to this FilingUnitVersion.
**Behavior:** Single-segment variant of §1.11.
**Retention class:** durable.
**Error modes:** undefined on miss.
**Implementation note:** Backed by same index as §1.11 with additional filter on `segment_id`.
### §1.13 `lookup_visibility_class(filing_unit_version_ref: FilingUnitVersionRef): VisibilityClass`
**Owner:** EC database access layer.
**Caller:** Artifact 5 §6.5 `classify_cross_version_sharing` (cross-version sharing visibility-class equality check per HIGH-A5-3 R0.2 fix).
**Returns:** VisibilityClass enum (per Artifact 1 §A.6: public_open / public_redacted / sealed_unredacted / sealed / firewalled).
**Behavior:** Pure read; computes max_visibility_class across all parts of the FilingUnitVersion (per INV-O-FILING-PART-VIS-1: artifact.visibility_class = max across filing_parts).
**Retention class:** durable; visibility_class can be advanced via INV-A-TAINT-INFECTIOUS-1 lattice but never demoted.
**Error modes:** throws `filing_unit_version_not_found` on missing ref (caller violates schema invariant).
**Implementation note:** Backed by FilingUnitVersion table with denormalized `max_visibility_class` field (lazily updated on segment overlay changes).
### §1.14 `lookup_access_overlays(filing_unit_version_ref: FilingUnitVersionRef): AccessOverlay[]`
**Owner:** EC database access layer.
**Caller:** Artifact 5 §6.5 `classify_cross_version_sharing` (access-overlay equality check per HIGH-A5-3 R0.2 fix).
**Returns:** array of AccessOverlay records that target this FilingUnitVersion or any of its filing_parts.
**Behavior:** Aggregates overlays across all granularities (filing_unit_version, filing_part, segment) that this FilingUnitVersion ranges over.
**Retention class:** durable.
**Error modes:** empty array on no overlays.
**Implementation note:** Conceptually = union of `lookup_overlays_at_part_granularity` over all parts plus version-level overlays. Implementation MAY be a single indexed query.
### §1.15 `lookup_stale_memory(document_id: string, field: string): DerivedMemory | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 5 §9.2 `resolve_field_value` (INV-EXT-7 field-level resolution); Artifact 4 §17.4 `resolve_field_at_read_time`.
**Returns:** the most recent DerivedMemory record for `(document_id, field)` that has `stale_pending_source_changed = true`, OR the most recent stable DerivedMemory if no stale record exists.
**Behavior:** Returns the historically-extracted value (per INV-MVC-2 stale-marking + V4-§0.6-MVC-EXT INV-EXT-7).
**Retention class:** durable; stale memories persist with explicit framing (per Artifact 5 §9.1).
**Error modes:** undefined when no historical extraction exists.
**Implementation note:** Backed by derived_memories table with composite index on `(document_id, field)`. The "stale" flag drives the §9.2 resolution logic.
### §1.16 `lookup_active_re_extraction(document_id: string): ExtractionRunRecord | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 5 §9.2 `resolve_field_value`.
**Returns:** the active re-extraction ExtractionRunRecord for the document, or undefined if no active re-extraction.
**Behavior:** Filters extraction_run_records by `(filing_unit_ref = document_id, current_extraction_state IN ("running", "degraded"))`.
**Retention class:** ExtractionRunRecord is durable per INV-K-MANIFEST-DURABLE-1 (Artifact 3 §15.2).
**Error modes:** undefined when no active re-extraction.
**Implementation note:** Backed by extraction_run_records table indexed on `(filing_unit_ref, current_extraction_state)`.
### §1.17 `lookup_re_extraction_value(re_extraction: ExtractionRunRecord, field: string): any | null`
**Owner:** EC database access layer.
**Caller:** Artifact 5 §9.2 `resolve_field_value` (succeeded-fields branch).
**Returns:** the field value extracted by this re-extraction run, or null if the field was not extracted.
**Behavior:** Reads the per-field output from the active extraction run's output payload.
**Retention class:** ExtractionRunRecord output is durable.
**Error modes:** null on no value.
**Implementation note:** Implementation reads `extraction_run.output_payload[field]` (typed by ExtractionStrategy.field_schema).
### §1.18 `lookup_artifacts_by_hash(hash_kind: string, candidate_hash: string): SourceArtifact[]`
**Owner:** EC database access layer.
**Caller:** Artifact 5 §10.3 `detect_hash_collision`.
**Returns:** array of SourceArtifacts whose `${hash_kind}_hash` field matches `candidate_hash`.
**Behavior:** Per Artifact 5 §10 multi-hash discipline: each SourceArtifact has 6 hash kinds (raw_file, normalized_binary, normalized_text, page-level, chunk-level, segment-level). This helper indexes one kind at a time.
**Retention class:** SourceArtifact is durable; hashes are immutable post-create.
**Error modes:** empty array on no match; never throws.
**Implementation note:** Backed by 6 separate indexes (one per hash_kind) per Artifact 5 §10.2 multi-hash registry. Coding agents MUST iterate hash_kinds rather than computing a composite index.
### §1.19 `lookup_existing_artifact_by_hash(hash: ContentHashRef): SourceArtifact | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §7.5 `validate_external_upload` (file-safety controls; duplicate detection).
**Returns:** the FIRST SourceArtifact whose `raw_file_hash` matches, or undefined.
**Behavior:** Convenience wrapper over §1.18 for raw_file_hash kind. Used at upload time to detect duplicate uploads.
**Retention class:** durable.
**Error modes:** undefined on no match.
**Implementation note:** Equivalent to `lookup_artifacts_by_hash("raw_file", hash)[0]`.
### §1.20 `lookup_share_token_policy(share_token_id: string): ShareTokenPolicy | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §5.2 `revoke_share_token`.
**Returns:** ShareTokenPolicy schema (per Artifact 4 §5.1) or undefined.
**Behavior:** Read by share_token_id (NOT by raw token; raw tokens never stored).
**Retention class:** durable; revocation lifecycle per Artifact 4 §5.2.
**Error modes:** undefined on miss.
**Implementation note:** Backed by share_token_policies table indexed on `share_token_id`.
### §1.21 `lookup_active_sessions_by_share_token(share_token_id: string): ShareLinkSession[]`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §5.2 `revoke_share_token` (active-session disposition).
**Returns:** array of currently-active ShareLinkSession records for this share token.
**Behavior:** Filters share_link_sessions table by `(share_token_id, session_state IN ("active"))`.
**Retention class:** ShareLinkSession is durable; active state lifecycle per Artifact 4 §6.
**Error modes:** empty array on no active sessions.
**Implementation note:** Backed by share_link_sessions table with composite index on `(share_token_id, session_state)`.
### §1.22 `lookup_native_session_scope_binding(session_id: string): NativeSessionScopeBinding | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §11.4 `dispatch_to_executor` (specialist sub-agent spawn validation per V4-I-3).
**Returns:** NativeSessionScopeBinding schema (per Artifact 4 §6.1) or undefined.
**Behavior:** Read by `parent_session_id`.
**Retention class:** durable for session lifetime.
**Error modes:** undefined on no binding (caller must construct).
**Implementation note:** Backed by native_session_scope_bindings table indexed on `parent_session_id`.
### §1.23 `lookup_capability_policy(capability_policy_ref: string): CapabilityPolicy | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §8.4 `check_capability_permitted`; §11.5 capability dispatch.
**Returns:** CapabilityPolicy schema (per Artifact 4 §8.1).
**Behavior:** Read by `policy_id`.
**Retention class:** durable.
**Error modes:** undefined on miss.
**Implementation note:** Backed by capability_policies table indexed on `policy_id`. May resolve via parent_policy_ref chain (delegated to §1.24).
### §1.24 `lookup_parent_policy(policy: CapabilityPolicy): CapabilityPolicy | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §8.4 `check_capability_permitted` (recursive parent walk).
**Returns:** the parent CapabilityPolicy (per V4-I-2 namespace registry hierarchy), or undefined if root.
**Behavior:** Reads `policy.parent_policy_ref` and dispatches to §1.23.
**Retention class:** durable.
**Error modes:** undefined when policy is root.
**Implementation note:** One-step parent walk; recursion is at the caller level.
### §1.25 `lookup_observation(observation_id: string): CourtDispositionObservation | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §14.2 `format_disposition_citation` (supersession lookup).
**Returns:** CourtDispositionObservation schema (per Artifact 2 §14.1).
**Behavior:** Read by `observation_id`.
**Retention class:** durable; observations are immutable post-create.
**Error modes:** undefined on miss.
**Implementation note:** Backed by court_disposition_observations table indexed on `observation_id`.
### §1.26 (Reserved — `lookup_csa_injection_tier_policy` REMOVED in R0.2 per CSA extraction)
[R0.2 PATCH per CSA extraction 2026-05-04: `lookup_csa_injection_tier_policy(policy_ref: string): CSAInjectionTierPolicy | undefined` REMOVED. The helper previously read CSAInjectionTierPolicy from EC database for Artifact 4 §18.3 CSA injection runtime. CSAInjectionTierPolicy was DELETED from Artifact 4 R0.4 §18 (consumer-side session-orientation orchestration deferred to DOC72). Helper is no longer needed. §1.26 subsection number reserved to preserve numbering of subsequent §1.X entries.]
### §1.27 `lookup_latest_rollup(corpus_ref: CorpusRef, rollup_kind: string): RecentActivityRollup | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 2 §25 (Group N consumer surface). [R0.2 PATCH per CSA extraction 2026-05-04: previously also called from Artifact 4 §18.3 CSA injection runtime; §18 DELETED in Artifact 4 R0.4. DOC72-side session-orientation orchestration (when shipped) will likely consume this helper too.]
**Returns:** the most recent RecentActivityRollup (per Artifact 1 §16.2) for this corpus and rollup_kind, or undefined.
**Behavior:** Filters recent_activity_rollups table by `(corpus_ref, rollup_kind)` ordered by `produced_at DESC LIMIT 1`.
**Retention class:** rollups are durable per V3.7 OBL-EC-NEW-N-ROLLUP-01.
**Error modes:** undefined when no rollup exists.
### §1.28 `lookup_derived_memory(memory_id: string): DerivedMemory | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §19.2 `filter_stale_memories_at_read`.
**Returns:** DerivedMemory record (per Artifact 1 §A.2 schema cross-reference; canonical home: V1.5.1 §6).
**Behavior:** Read by `memory_id`.
**Retention class:** durable.
**Error modes:** undefined on miss.
### §1.29 `lookup_filing_unit(filing_unit_ref: FilingUnitRef): FilingUnit | undefined`
**Owner:** EC database access layer.
**Caller:** multiple read paths in Artifact 2 + Artifact 4 + Artifact 5.
**Returns:** FilingUnit schema or undefined.
**Behavior:** Read by `filing_unit_id`.
**Retention class:** durable.
**Error modes:** undefined on miss.
### §1.30 `lookup_source_artifact(artifact_id: SourceArtifactRef): SourceArtifact | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §16.3 `resolve_share_link_search_result`; Artifact 5 §10.3 dedup; multiple read paths.
**Returns:** SourceArtifact schema (per Artifact 5 §2.2) or undefined.
**Behavior:** Read by `artifact_id`.
**Retention class:** durable.
**Error modes:** undefined on miss.
### §1.31 `lookup_binding_outcome(binding_id: string, source_event_id: string): BindingOutcomeRecord | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §17.2 read path consumer.
**Returns:** BindingOutcomeRecord (per Artifact 2 §K + Artifact 3 §13.5).
**Behavior:** Read by composite key.
**Retention class:** durable per INV-K-MANIFEST-DURABLE-1.
**Error modes:** undefined on miss.
### §1.32 `lookup_shared_corpus_views(host_ref: SessionRef, target_ref: NodeRef): SharedCorpusView[]`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §4.2 `filter_results_per_shared_corpus_view`.
**Returns:** array of SharedCorpusView records owned by `host_ref` that target `target_ref` (corpus, filing_unit, etc.).
**Behavior:** Filters shared_corpus_views table by host + target.
**Retention class:** durable.
**Error modes:** empty array on no views.
### §1.33 `lookup_shared_corpus_view(view_id: string): SharedCorpusView | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §5.1 `grant_share_link` (single-view lookup).
**Returns:** SharedCorpusView schema or undefined.
**Behavior:** Read by `view_id`.
**Retention class:** durable.
**Error modes:** undefined on miss.
### §1.34 `lookup_utility_signal_policy(policy_ref: string): UtilitySignalPolicy | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §7.1 (utility signal capture per V4-I-6).
**Returns:** UtilitySignalPolicy schema or undefined.
**Behavior:** Read by `policy_id`.
**Retention class:** durable.
**Error modes:** undefined on miss.
### §1.35 `lookup_external_upload_file_safety_controls(controls_ref: string): ExternalUploadFileSafetyControls | undefined`
**Owner:** EC database access layer.
**Caller:** Artifact 4 §7.5 `validate_external_upload`.
**Returns:** ExternalUploadFileSafetyControls schema (per Artifact 4 §7.4).
**Behavior:** Read by `controls_id`.
**Retention class:** durable.
**Error modes:** undefined on miss.
### §1.36 `lookup_reason_code(reason_code: string): ReasonCodeRegistryEntry | undefined`
**Owner:** EC database access layer (reason-code registry).
**Caller:** Artifact 4 §15.X (search router denial messaging per V4-I-DENIAL-1); §10.X executor dispatch.
**Returns:** ReasonCodeRegistryEntry (per V3-I-DENIAL-1 reason-code registry).
**Behavior:** Read by `reason_code` namespace string.
**Retention class:** durable; reason-code registry is policy-controlled.
**Error modes:** undefined for unknown reason codes (UI falls back to generic denial message).
**Implementation note:** Per V4-I-2 namespace registry compliance: all reason codes MUST be registered before use.
---
## §2. Pure functions (~20 helpers)
Owner home: **Inline declarations per artifact** (no canonical home file; logic is small enough that each artifact MAY declare its own copy).
These are deterministic, side-effect-free utility functions. They take inputs by value and return computed outputs without touching durable state. Each artifact that calls a pure function MAY declare its own inline copy with the canonical signature; coding agents implementing across artifacts MUST honor identical semantics.
Common conformance rules for §2 helpers:
- No side effects.
- Deterministic for identical inputs.
- No DB reads; no external calls.
- Each artifact MAY have its own inline copy; same signature MUST appear identically across copies.
- Implementations are typically <30 LOC; per V1.6 design tradeoff (inlining is cheaper than cross-artifact dependency).
### §2.1 `most_restrictive_derived_memory(policies: DerivedMemoryPolicy[]): DerivedMemoryPolicy`
**Owner:** Inline at Artifact 4 §4.3 `resolve_effective_shared_corpus_view`.
**Caller:** Artifact 4 §4.3 (deny-wins precedence per V4-I-1).
**Returns:** the policy in the array with the most restrictive derived_memory_visibility.
**Behavior:** Compares policies on a 5-tier lattice (visible_full > visible_summary > visible_existence > suppressed > hidden); returns the one closest to "hidden". Per INV-I-1 + V4-I-1 deny-wins.
**Lattice ordering (most restrictive first):** `hidden` > `suppressed` > `visible_existence` > `visible_summary` > `visible_full`.
**Error modes:** throws on empty array (caller violates contract); throws on undefined policy entry.
**Implementation note:** Coding agents MUST use the lattice ordering above; alphabetical or insertion-order tie-breaking is non-conformant.
### §2.2 `most_restrictive_host_annotation(policies: HostAnnotationVisibility[]): HostAnnotationVisibility`
**Owner:** Inline at Artifact 4 §4.3.
**Caller:** Artifact 4 §4.3.
**Returns:** the policy with the most restrictive host_annotation_visibility.
**Lattice ordering (most restrictive first):** `hidden` > `redacted` > `summarized` > `visible`.
**Error modes:** throws on empty array.
### §2.3 `lowest_in_lattice(visibility_classes: VisibilityClass[]): VisibilityClass`
**Owner:** Inline at Artifact 4 §4.3 + Artifact 3 §7 (mixed-class context_packet output).
**Caller:** Artifact 4 §4.3 (visibility_ceiling computation per V4-I-1); Artifact 3 §7 INV-A-TAINT-INFECTIOUS-1 lattice.
**Returns:** the most restrictive visibility class.
**Lattice ordering (most restrictive last in PERMISSIVENESS = most restrictive first in restriction):** `firewalled` > `sealed` > `sealed_unredacted` > `public_redacted` > `public_open`.
**Error modes:** throws on empty array.
**Implementation note:** Per Artifact 1 §A.6 VisibilityClass enum + INV-A-TAINT-INFECTIOUS-1 (Artifact 3 §7.1): same lattice across all consumers.
### §2.4 `most_restrictive_temporal(temporal_modes: TemporalMode[]): TemporalMode`
**Owner:** Inline at Artifact 4 §4.3.
**Caller:** Artifact 4 §4.3 (deny-wins per V4-I-1).
**Returns:** the most restrictive temporal scope.
**Lattice ordering (most restrictive first):** `frozen_at_share_grant` > `current_minus_window` > `live`.
**Error modes:** throws on empty array.
**Implementation note:** Per V4-I-4 view_temporal_mode enum.
### §2.5 `intersect_document_scopes(scopes: DocumentScope[]): DocumentScope`
**Owner:** Inline at Artifact 4 §4.3.
**Caller:** Artifact 4 §4.3 (deny-wins per V4-I-1).
**Returns:** intersection of multiple DocumentScope objects (per Artifact 4 §4.1 SharedCorpusView.document_scope union type).
**Behavior:**
- All `{kind: "all_documents"}` scopes union to `{kind: "all_documents"}`.
- Any `{kind: "explicit_document_list"}` narrows to the intersection of refs.
- Mixed `explicit_document_list` + `filing_unit_version_list` produce intersection across both lists.
- `{kind: "structural_selector"}` requires evaluation against actual documents; intersection becomes most-restrictive selector.
**Error modes:** throws on empty array; returns `{kind: "explicit_document_list", document_refs: []}` on empty intersection (caller MUST treat as deny-all).
### §2.6 `max_visibility_class(visibility_classes: VisibilityClass[]): VisibilityClass`
**Owner:** Inline at Artifact 2 §11.4.X `check_filing_part_visibility` + multiple consumers.
**Caller:** Artifact 2 §11.4.X (INV-O-FILING-PART-VIS-1: artifact.visibility_class = max across filing_parts).
**Returns:** the MOST restrictive visibility class (per INV-A-TAINT-INFECTIOUS-1).
**Behavior:** Same lattice as §2.3.
**Implementation note:** This and §2.3 are the same function; named separately for caller clarity. Same semantics.
### §2.7 `canonical_key_complete(identity: FilingUnitIdentity): boolean`
**Owner:** Inline at Artifact 2 §11.5.
**Caller:** Artifact 2 §11.5 `lookup_or_create_filing_unit`.
**Returns:** true iff `identity` has all 6 canonical-key fields populated (court_id, case_number, docket_entry_no, filing_kind, filing_party, filing_date) per V3-O-1.
**Behavior:** Pure boolean check on field presence (not normalization).
**Error modes:** never throws; returns false on missing fields.
### §2.8 `classify_collision_severity(collision_kind: string, matches: SourceArtifact[], candidate: SourceArtifact): "low" | "medium" | "high"`
**Owner:** Inline at Artifact 5 §10.4 (per MED-A5-6 R0.2 fix).
**Caller:** Artifact 5 §10.4 HashCollisionDetectedReceipt severity assignment.
**Returns:** severity tier per Artifact 5 §10.4.
**Behavior:**
```typescript
function classify_collision_severity(
collision_kind: string,
matches: SourceArtifact[],
candidate: SourceArtifact
): "low" | "medium" | "high" {
// High: cross-visibility-class single-kind match (suspect)
if (matches.some(m => m.visibility_class !== candidate.visibility_class)) {
return "high";
}
// Medium: single-kind partial in non-content-derivation pattern
if (collision_kind === "raw_file" || collision_kind === "normalized_binary") {
return "medium";
}
// Low: derivation-pattern collisions (normalized_text, page, chunk)
return "low";
}
```
### §2.9 `compute_intersection_across_kinds(matches_per_kind: Record<string, SourceArtifact[]>): SourceArtifact[]`
**Owner:** Inline at Artifact 5 §10.3.
**Caller:** Artifact 5 §10.3 `detect_hash_collision`.
**Returns:** array of SourceArtifacts that match across ALL hash kinds (true known-duplicate).
**Behavior:** Computes set intersection over all hash_kind buckets; returns artifacts present in every bucket.
**Implementation note:** Coding agents MUST treat empty buckets correctly (a missing hash_kind for the candidate means no constraint from that kind, NOT empty intersection).
### §2.10 `matches_pattern(pattern: CapabilityPattern, capability_id: string, namespace: string): boolean`
**Owner:** Inline at Artifact 4 §8.4.
**Caller:** Artifact 4 §8.4 `check_capability_permitted`.
**Returns:** true iff the capability_id matches the pattern within the namespace.
**Behavior:** Glob-style match per V4-I-2 CapabilityPattern grammar (e.g., `calendar.*` matches `calendar.create_event`; `calendar.*.read` matches `calendar.events.read`).
**Implementation note:** Pattern grammar is glob-only in V1.6; regex is V1.7+ per V4 deferral inventory.
### §2.11 `matches_selector(candidate: BindingCandidate, selector: StructuralSelector): boolean`
**Owner:** Inline at Artifact 2 §19.4 (`evaluate_binding_filter`).
**Caller:** Artifact 2 §19.4; Artifact 3 §13.8 `validate_binding_selectors`.
**Returns:** true iff candidate matches the structural selector.
**Behavior:** Per V3-K-1 StructuralSelector schema (Artifact 2 §19.3): selector kinds = `topic_assignment`, `legal_metadata_field_value`, `filing_unit_version_attribute`, `pattern_library_match`. Each kind has its own match grammar.
**Implementation note:** Coding agents MUST NOT introduce new selector kinds without architect approval; V1.6 enum is closed.
### §2.12 `matches_content_type_filter(candidate: BindingCandidate, filter: ContentTypeFilter): boolean`
**Owner:** Inline at Artifact 2 §19.4.
**Caller:** Artifact 2 §19.4 `evaluate_binding_filter`.
**Returns:** true iff candidate's content type passes the filter (per V4-K-1 axes).
**Behavior:** Filter grammar limited to `kind`, `mime`, `legal_kind`, `filing_role`, `motion_type`.
### §2.13 `auto_derive_polarity(disposition: RulingDisposition): RulingDispositionPolarity`
**Owner:** Inline at Artifact 2 §13.5.
**Caller:** Artifact 2 §13.5 (V4-O-5 RulingDispositionPolarity).
**Returns:** RulingDispositionPolarity enum (per Artifact 2 §13.5: party_favorable, party_unfavorable, mixed, neutral, unknown).
**Behavior:** Heuristic auto-derivation from disposition_kind + outcome text. Lazy default = "unknown"; explicit user override may set otherwise.
**Implementation note:** Heuristic rules:
- `granted` → `party_favorable` (for moving party); `party_unfavorable` (for non-moving party).
- `denied` → opposite.
- `granted_in_part_denied_in_part` → `mixed`.
- `withdrawn` / `mooted` → `neutral`.
- everything else → `unknown`.
Coding agents MUST default to `unknown` when ambiguous; explicit lazy override is preferred over speculative derivation.
### §2.14 `disposition_applies_to_subset(d: RulingDisposition): boolean`
**Owner:** Inline at Artifact 2 §13.4.
**Caller:** Artifact 2 §13.4 `validate_ruling_disposition` (V4-O-4 mandatory scope_targets per INV-O-DISPOSITION-1).
**Returns:** true iff the disposition applies to a subset of FilingUnit's defendants/claims (rather than all).
**Behavior:** Returns true iff `d.disposition_event_targets_partial = true` OR `d.scope_targets.defendant_refs.length < FilingUnit.defendant_refs.length` etc.
**Implementation note:** Pure check on disposition shape.
### §2.15 `is_scope_targets_empty(targets: ScopeTargets): boolean`
**Owner:** Inline at Artifact 2 §13.4.
**Caller:** Artifact 2 §13.4.
**Returns:** true iff all of `defendant_refs`, `claim_refs`, `motion_chain_ref`, `filing_chain_ref` are empty/undefined.
**Behavior:** Pure structural check.
### §2.16 `format_canonical_citation(cited_case: CaseRef): string`
**Owner:** Inline at Artifact 2 §16.1.
**Caller:** Artifact 2 §16.1 `render_citation`.
**Returns:** formatted citation string per Bluebook canonical format (e.g., "Smith v. Jones, 123 F.3d 456 (2d Cir. 2024)").
**Behavior:** Resolves CaseRef to ResolvedCaseIdentity; formats per case parties + reporter info.
**Implementation note:** V1.6 supports federal court Bluebook format only; state-court formats deferred V1.6.1.
### §2.17 `formatSupersessionNote(superseded_at: ISO8601, superseding_obs: CourtDispositionObservation | undefined): string`
**Owner:** Inline at Artifact 2 §14.2.
**Caller:** Artifact 2 §14.2 `format_disposition_citation`.
**Returns:** human-readable note like "(superseded 2024-03-15 by ECF #145)".
**Behavior:** Pure string formatting; if superseding_obs is undefined, formats as "(superseded 2024-03-15 — superseding ruling not in record)".
### §2.18 `get_dedup_thresholds(domain_profile: string): DedupThresholds`
**Owner:** Inline at Artifact 2 §5.4.
**Caller:** Artifact 2 §5.4 (INV-J-TOPIC-DEDUP-1 per V4-J-4).
**Returns:** DedupThresholds for the given domain profile (legal: 0.93 minimum; default: 0.80).
**Behavior:** Per V4-J-4 + Artifact 2 §5.4: legal corpora require 0.93 floor for topic dedup; lower threshold blocks merge to prevent false-positive dedup.
**Implementation note:** Domain-profile lookup: legal → 0.93; default → 0.80; future profiles configurable.
### §2.19 `extract_namespace(capability_id: string): string`
**Owner:** Inline at Artifact 4 §8.4.
**Caller:** Artifact 4 §3.2 `check_capability_permitted` + namespace registry compliance.
**Returns:** the namespace prefix of the capability_id (e.g., `extract_namespace("calendar.create_event") === "calendar"`).
**Behavior:** Splits on first `.` separator.
**Implementation note:** V1.6 grammar: namespace is the first `.`-separated segment; multi-level namespaces (e.g., `app.subcapability.action`) treat the FIRST segment as namespace.
### §2.20 `dispatch_apply(env: PBEOperationEnvelope, effect: KernelEffect): void`
**Owner:** Inline at Artifact 3 §2.3.
**Caller:** Artifact 3 §2.3 effect-application dispatch.
**Returns:** void (side effects on EC state via per-effect-kind apply_* helpers in §6).
**Behavior:** Dispatches to per-effect-kind helper based on `effect.effect_kind` enum (per Artifact 3 §4.2 22-value enum).
**Implementation note:** Pure dispatch logic; the actual side-effecting work lives in §6 specialized helpers.
### §2.21 `classify_search_receipt_retention(retention_class_field: string): "ephemeral_session_lifetime" | "durable"`
**Owner:** Inline at Artifact 4 §20.2 (per INV-M-RETENTION-1).
**Caller:** Artifact 4 §20.2.
**Returns:** retention class enum.
**Behavior:** Classification table per Artifact 4 §20.2; specific retention_class fields map to ephemeral vs durable per V4-M-RETENTION.
### §2.22 `classify_trust_posture(source_event: SourceEvent): TrustPosture`
**Owner:** Inline at Artifact 2 §20.5 (`create_corpus_membership`).
**Caller:** Artifact 2 §20.5; Artifact 3 §13.X.
**Returns:** TrustPosture enum (per V3-K-9: `verified_authoritative`, `verified_secondary`, `user_assertion`, `untrusted`).
**Behavior:** Maps acquisition_shape to default trust_posture per V4-K-FANOUT canonical map (e.g., `binding_fire_pacer` → `verified_authoritative`; `share_link_external_upload` → `untrusted`).
**Implementation note:** Canonical map per Artifact 5 §2.4 AcquisitionShape enum.
### §2.23 `enumerate_content_hashes(source_event: SourceEvent): ContentHashRef[]`
**Owner:** Inline at Artifact 2 §20.5.
**Caller:** Artifact 2 §20.5 `create_corpus_membership`.
**Returns:** array of content hashes from source_event (raw_file_hash, normalized_text_hash, etc.).
**Behavior:** Pure projection from source_event into ContentHashRef array per Artifact 5 §10 multi-hash discipline.
### §2.24 `derive_source_instance_id(source_event: SourceEvent): string`
**Owner:** Inline at Artifact 2 §20.5.
**Caller:** Artifact 2 §20.5 `create_corpus_membership`.
**Returns:** stable source_instance_id derived from source_event.
**Behavior:** Per V3-K-9 source_instance_id pattern: deterministic hash of (source_kind + binding_id + acquisition_timestamp + raw_file_hash). Same event produces same id; different events with identical content produce same id (intentional dedup signal).
### §2.25 `derive_visibility_snapshot(source_event: SourceEvent): VisibilitySnapshotRef`
**Owner:** Inline at Artifact 2 §20.5.
**Caller:** Artifact 2 §20.5.
**Returns:** snapshot of visibility-class state at event time.
**Behavior:** Captures visibility_class derived from acquisition_shape + binding settings + source artifact visibility; per V4-K-EVICTION-1 sealed_at_intake.
### §2.26 `should_auto_confirm(binding: SourceBinding, source_event: SourceEvent): boolean`
**Owner:** Inline at Artifact 2 §20.5.
**Caller:** Artifact 2 §20.5 `create_corpus_membership` (membership_state assignment).
**Returns:** true iff CorpusMembershipRecord should auto-confirm (vs landing in candidate state).
**Behavior:** Per V3-K-9 + V4-K-FANOUT auto-confirm rules:
- `binding.auto_confirm_when_high_trust = true` AND `source_event.trust_posture = "verified_authoritative"` → true.
- otherwise → false (lands in candidate, requires user review).
### §2.27 `validate_threshold_floor(threshold: number, domain_profile: string): boolean`
**Owner:** Inline at Artifact 2 §5.4.
**Caller:** Artifact 2 §5.4.
**Returns:** true iff threshold is at or above the floor for the domain profile.
**Behavior:** Legal: floor = 0.93; default: floor = 0.80.
### §2.28 `format_base_citation(obs: CourtDispositionObservation): string`
**Owner:** Inline at Artifact 2 §14.2.
**Caller:** Artifact 2 §14.2 (used by `format_disposition_citation`).
**Returns:** base citation without supersession note.
### §2.29 `is_legal_corpus_corpus_ref(refs: string[]): boolean` / `is_legal_case_matter_ref(refs: string[]): boolean` / `has_filing_unit_refs(refs: string[]): boolean` / `is_legal_activity_kind(entry: any): boolean`
**Owner:** Inline at Artifact 2 §25 (Group N consumer surface).
**Caller:** Artifact 2 §25 (HIGH-A2-4 R0.2 fix; consumer behavior contract).
**Returns:** boolean per name.
**Behavior:** Domain-detection predicates for legal-corpus-aware RecentActivityRollup entries (per HIGH-A2-4: domain_profile = "legal" detection via three OR-paths).
---
## §3. Persistence helpers (~15 helpers)
Owner home: **EC persistence runtime** (per V3.7 OBL-EC-NEW-* row family).
These are write-path helpers that persist durable state to the EC database. All are subject to INV-15.7.8 (PrimaryPBEOrchestrator sole-writer) — direct invocation by V1.6 release wave artifact code is permitted ONLY when called inside a kernel envelope's effect-application phase (per Artifact 3 §1.4 + §2.3). Specialist sub-agents (memory_agent, document_intelligence_agent) MUST NOT call persistence helpers directly per INV-15.7.9.
Common conformance rules for §3 helpers:
- All persist_* helpers run inside a kernel envelope effect-application context.
- All are durable (per INV-V16-RETENTION-DURABLE-1) unless explicitly marked ephemeral.
- All emit a corresponding receipt (per V3.7 OBL-EC-NEW-RECEIPT-* row family).
- All are idempotent on retry (caller responsible for envelope_id deduplication; per Artifact 3 §1.4 envelope-replay semantics).
- All honor policy_generation_id capture at write time (per V4-K-INV-DEDUP-3).
- Coding agents MUST NOT bypass kernel envelope path; persist_* helpers fail with `bypass_kernel_violation` if called outside an active envelope effect-application.
### §3.1 `persist_state_transition(ref: SessionProfileRef, updated: SessionProfile, reason_code: string): SessionProfile`
**Owner:** EC persistence runtime.
**Caller:** Artifact 4 §2.5 SessionProfile state transition.
**Returns:** the persisted SessionProfile (with updated `updated_at`).
**Behavior:** Persists the new SessionProfile state; emits SessionProfileStateTransitionReceipt.
**Retention class:** durable; SessionProfile history maintained for audit.
**Error modes:** throws `invalid_state_transition` if transition violates §2.5 state machine; throws `bypass_kernel_violation` if not in envelope context.
**Implementation note:** Backed by a state-machine validator (`validate_state_transition`) before write.
### §3.2 `persist_share_token_policy(token: ShareTokenPolicy): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 4 §5.1 `grant_share_link` (per CRIT-A4-3 R0.2 fix).
**Returns:** void; ShareTokenPolicy persisted to share_token_policies table.
**Behavior:** Persists ShareTokenPolicy; raw token NEVER stored, only token_hash. Emits ShareTokenPolicyCreatedReceipt.
**Retention class:** durable.
**Error modes:** throws `duplicate_share_token_id` if token.share_token_id already exists; throws `bypass_kernel_violation`.
**Implementation note:** Per CRIT-A4-3 fix: invocation MUST be downstream of kernel envelope construction with effect_kind = "share_link_grant" (Artifact 3 §4.3.9). Coding agents MUST construct envelope FIRST, persist row SECOND, in same transaction.
### §3.3 `persist_share_token_revocation(share_token_id: string, revocation_params: ShareTokenRevocation): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 4 §5.2 `revoke_share_token`.
**Returns:** void.
**Behavior:** Persists ShareTokenRevocation; emits ShareTokenRevokedReceipt.
**Retention class:** durable.
**Error modes:** throws `share_token_not_found`; throws `already_revoked`.
**Implementation note:** Per HIGH-A4-3 R0.2 clarification: ShareTokenRevocation entity (Artifact 4 §5.2) is canonical; share_link_revoke effect_kind on KernelEffect (Artifact 3 §4.3.10) is the runtime classification. Persistence helper writes the entity; kernel envelope writes the effect.
### §3.4 `persist_coverage_receipt_internal(receipt: SearchCoverageReceiptInternal): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 4 §13.X `emit_search_coverage_receipts`.
**Returns:** void.
**Behavior:** Persists internal-only SearchCoverageReceipt (full executor counts, internal scope info per V4-M-2). Emits CoverageReceiptInternalCreatedReceipt.
**Retention class:** durable per INV-M-RETENTION-1 (V4-M-RETENTION).
**Error modes:** throws `bypass_kernel_violation`.
**Implementation note:** Per V4-M-2 internal/visible split: internal receipt has full executor coverage data; visible receipt has user-facing summary only.
### §3.5 `persist_coverage_receipt_visible(receipt: SearchCoverageReceiptVisible): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 4 §13.X `emit_search_coverage_receipts`.
**Returns:** void.
**Behavior:** Persists user-facing SearchCoverageReceipt subset.
**Retention class:** durable.
**Error modes:** throws `bypass_kernel_violation`.
### §3.6 `persist_batch_review_operation(batch: BatchReviewOperation): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 2 §23.2 `apply_batch_review_operation` (V3-AT-20 BatchReviewOperation per-item).
**Returns:** void.
**Behavior:** Persists BatchReviewOperation receipt with per-item status.
**Retention class:** durable.
**Error modes:** throws `bypass_kernel_violation`.
**Implementation note:** Per Artifact 3 §14.4 batch operation partial-failure semantics (V4-AT-PARTIAL): each item's outcome is independently persisted; batch-level rollback is bounded by INV-K-BATCH-PARTIAL-1.
### §3.7 `record_contribution_state_transition(contribution_id: string, new_state: ContributionState, reason: string): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 2 §23.3 (CorpusBindingContribution state transition).
**Returns:** void.
**Behavior:** Persists state-transition entry on CorpusBindingContribution ledger; emits ContributionStateTransitionReceipt.
**Retention class:** durable per INV-K-EVICTION-1.
**Error modes:** throws `invalid_state_transition`; throws `bypass_kernel_violation`.
**Implementation note:** Per V2 patch L5 INV-K-HEALTH-1: contribution state lifecycle is `confirmed → soft_deleted` or `confirmed → rejected` or `confirmed → extraction_failed`. State machine enforced at validation.
### §3.8 `archive_partial_results_for_audit_only(run: ExtractionRunRecord): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 5 §8.1 `handle_document_artifact_version_changed` (INV-EXT-6 in-flight cancellation).
**Returns:** void.
**Behavior:** Marks ExtractionRunRecord as archived (cancelled); flips `audit_only_no_evidence = true` on partial outputs; partial outputs remain queryable in audit view but NEVER returned by search.
**Retention class:** durable per INV-V16-RETENTION-DURABLE-1; reference-counted GC at audit-retention horizon.
**Error modes:** throws `extraction_run_not_in_cancellable_state`.
**Implementation note:** Per Artifact 5 §8.3 audit-only retention discipline.
### §3.9 `create_native_session_scope_binding(binding: NativeSessionScopeBinding): NativeSessionScopeBinding`
**Owner:** EC persistence runtime.
**Caller:** Artifact 4 §11.4 `spawn_specialist_sub_agent`.
**Returns:** the persisted NativeSessionScopeBinding (with newly assigned id).
**Behavior:** Persists NativeSessionScopeBinding for new sub-agent session; emits NativeSessionScopeBindingCreatedReceipt.
**Retention class:** durable for session lifetime.
**Error modes:** throws `parent_binding_not_found`; throws `subagent_spawn_constraint_violation` if validation fails.
**Implementation note:** Per V4-I-3 NativeSessionScopeBinding expansion + V4-I-3 spawn validation.
### §3.10 `create_extraction_run(params: ExtractionRunParams): ExtractionRunRecord`
**Owner:** EC persistence runtime.
**Caller:** Artifact 5 §8.1 (after INV-EXT-6 in-flight cancellation); §6.X general extraction lifecycle.
**Returns:** newly created ExtractionRunRecord (with extraction_run_id assigned).
**Behavior:** Persists ExtractionRunRecord in `running` state; emits ExtractionRunCreatedReceipt.
**Retention class:** durable per INV-K-MANIFEST-DURABLE-1 (Artifact 3 §15.2).
**Error modes:** throws `binding_disabled` if binding is no longer active; throws `bypass_kernel_violation`.
### §3.11 `create_corpus_membership(binding: SourceBinding, source_event: SourceEvent): CorpusMembershipRecord`
**Owner:** EC persistence runtime (with envelope construction via kernel).
**Caller:** Artifact 2 §20.5.
**Returns:** newly created CorpusMembershipRecord.
**Behavior:** Per Artifact 2 §20.5 R0.2: composes inline pure helpers (§2.22-§2.26) and §3.10 to construct + persist CorpusMembershipRecord; separate state machine from extraction (per INV-K-MEMBERSHIP-EXTRACTION-1).
**Retention class:** durable.
**Error modes:** throws `binding_disabled`; throws `bypass_kernel_violation`.
**Implementation note:** Membership state machine is independent of extraction; membership confirms early (UI listing, metadata search) while extraction may take hours.
### §3.12 `register_capability_atomically(capability_id: string, namespace: string, attrs: CapabilityAttrs): void`
**Owner:** EC persistence runtime (with kernel envelope per Artifact 3 §4.3.X).
**Caller:** Artifact 4 §8.3 capability registration.
**Returns:** void.
**Behavior:** Atomically registers capability in DOC24 capability registry per V4-§0.4-1 (DOC24 owns; NOT EC) + V4-I-2 namespace registry compliance. Composes 3 effects: (a) register_capability, (b) create_graph_node for capability_id, (c) cache_entry for capability_id. All-or-nothing per Artifact 3 §14 batch atomicity.
**Retention class:** durable.
**Error modes:** throws `namespace_not_registered`; throws `duplicate_capability_id`.
**Implementation note:** Coding agents MUST submit ALL 3 effects in a single envelope per Artifact 3 §14.X batch_atomicity discipline.
### §3.13 `cache_entry(entry_kind: string, ref: string): void`
**Owner:** EC persistence runtime (cache layer).
**Caller:** Artifact 4 §8.3 (capability cache); various cache-layer consumers.
**Returns:** void.
**Behavior:** Persists or updates a cache entry. Cache layer is in-memory + spilled to durable backing per V3.7 OBL-EC-NEW-CACHE-LAYER-01.
**Retention class:** ephemeral with durable backing (per V3.7).
**Error modes:** never throws; cache writes are best-effort.
**Implementation note:** Distinct from durable persistence — cache_entry writes are reconstructible from durable state at any time.
### §3.14 `persist_topic_visibility_policy(policy: TopicVisibilityPolicy): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 2 §5.X policy creation flow.
**Returns:** void.
**Behavior:** Persists TopicVisibilityPolicy.
**Retention class:** durable.
**Error modes:** throws `duplicate_policy_id`.
### §3.15 `persist_pattern_library_visibility(policy: PatternLibraryVisibility): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 2 §6.X policy creation flow.
**Returns:** void.
**Behavior:** Persists PatternLibraryVisibility.
**Retention class:** durable.
### §3.16 `persist_corpus_profile_fork(fork: CorpusProfileFork): CorpusProfileFork`
**Owner:** EC persistence runtime.
**Caller:** Artifact 2 §9.3 `fork_corpus_profile` (V4-J-FORK).
**Returns:** the persisted CorpusProfileFork (with fork_id assigned).
**Behavior:** Per V4-J-FORK: persists CorpusProfileFork + ForkRelationshipEdge + transitive_descendants_of_root computation. Emits CorpusProfileForkCreatedReceipt.
**Retention class:** durable.
**Error modes:** throws `parent_profile_not_found`.
### §3.17 `persist_recent_activity_rollup(rollup: RecentActivityRollup): void`
**Owner:** EC persistence runtime.
**Caller:** Artifact 1 §16.2A Mechanism 4 RecentActivityRollup writer agent.
**Returns:** void.
**Behavior:** Persists RecentActivityRollup; honored by Group N consumer surface (Artifact 2 §25). [R0.2 PATCH per CSA extraction 2026-05-04: prior reference to "Artifact 4 §18" as consumer is REMOVED — §18 CSAInjectionTierPolicy was deleted in Artifact 4 R0.4 §18; consumer-side session-orientation orchestration deferred to DOC72 per `OBL-D73-RECENT-ACTIVITY-ROLLUP-CONSUMER-CONTRACT-01`.]
**Retention class:** durable per V3.7 OBL-EC-NEW-N-ROLLUP-01.
---
## §4. Notification / event emission helpers (~10 helpers)
Owner home: **DOC10 / Artifact 4 UI layer** (Q Dashboard surfacing).
These are user-facing notification / surfacing helpers. They take user-facing event data and dispatch to the Q Dashboard UI layer for display. None of these helpers persist durable state directly — instead, they emit *receipt* records (which §3 helpers persist) and trigger *UI events* that the dashboard consumes.
Common conformance rules for §4 helpers:
- Side effects = UI dispatch + receipt emission ONLY; NEVER direct DB writes.
- All helpers have a corresponding receipt schema (per Artifact 1 §A.* receipt taxonomy + Artifact 3 receipt store).
- All emit through the kernel envelope path when associated with a kernel-recorded event (e.g., emit during effect-application phase).
- Notification message templates are owned by DOC10 i18n catalog (per V4 §0.8-I18N V1.7+ note: V1.6 ships English-only).
- Per V4-§0.4-1: DOC10 / Artifact 4 UI layer is the canonical home for all user-facing surfaces.
### §4.1 `emit_user_notification(notification: UserNotification): void`
**Owner:** DOC10 / Artifact 4 UI layer.
**Caller:** Artifact 5 §8.1 (extraction restarted notification per INV-EXT-6); Artifact 4 §7.5 `validate_external_upload` (upload duplicate detected); Artifact 5 various retry/recovery paths.
**Returns:** void.
**Behavior:** Surfaces a user-facing notification card in the Q Dashboard notification panel; emits UserNotificationReceipt for audit.
**Receipt:** UserNotificationReceipt; durable per INV-V16-RETENTION-DURABLE-1.
**Schema:**
```typescript
type UserNotification = {
kind: string; // namespaced kind
// (e.g.,
// "extraction_restarted_due_to_source_change")
prior_run_id?: string; // context-specific fields
new_run_id?: string;
reason: string; // user-facing reason text
ref?: string; // related entity ref
action_buttons?: NotificationAction[]; // user actions
schema_version: 1;
};
```
**Implementation note:** Per V4-§0.4-1 DOC10 UI layer: notification routing is a DOC10 concern; V1.6 release wave artifacts call the helper but do not own UI rendering.
### §4.2 `emit_user_warning(warning_kind: string, context?: any): void`
**Owner:** DOC10 / Artifact 4 UI layer.
**Caller:** Artifact 4 §7.5 `validate_external_upload` (active content detected warning).
**Returns:** void.
**Behavior:** Surfaces a warning-severity notification (distinct from §4.1 info-level notification). Emits UserWarningReceipt.
**Receipt:** UserWarningReceipt; durable.
**Implementation note:** Warning kind is namespaced (e.g., "active_content_detected"). UI uses warning styling (yellow icon).
### §4.3 `emit_audit_log_entry(reason_code: string, session_ref: SessionRef): void`
**Owner:** DOC10 / Artifact 4 UI layer (audit surface).
**Caller:** Artifact 4 §15.X (search router denial messaging per V4-I-DENIAL-1).
**Returns:** void.
**Behavior:** Records an audit-log entry (visible to the host session via audit view per Artifact 4 audit surface).
**Receipt:** AuditLogEntryReceipt; durable.
**Implementation note:** Per V4-I-DENIAL-1 reason-code namespace registry: every reason_code emitted MUST be registered (per §1.36 lookup_reason_code).
### §4.4 `emit_recall_request_to_recipient(share_token_id: string): void`
**Owner:** DOC10 / Artifact 4 UI layer + email/notification subsystem.
**Caller:** Artifact 4 §5.2 `revoke_share_token` (notify recipient of revocation when downloaded_copies_disposition = "request_recall").
**Returns:** void.
**Behavior:** Sends a recall request notification to the share-link recipient. Emits RecallRequestEmittedReceipt.
**Receipt:** RecallRequestEmittedReceipt; durable.
**Error modes:** never throws; failure to deliver is logged but does not block revocation flow.
**Implementation note:** Recipient delivery channel = email when recipient_identity_mode includes email; in-app notification when recipient is OpenClaw user. V1.6: best-effort delivery; no acknowledgment tracking.
### §4.5 `emit_caching_tier_blocked_receipt(artifact: SourceArtifact, tier: "tier_1" | "tier_2"): CachingTierBlockedReceipt`
**Owner:** DOC10 / Artifact 4 UI layer (with persistence side effect).
**Caller:** Artifact 5 §11.1 `dispatch_caching_tier` (INV-B2-CACHING-1 enforcement).
**Returns:** the emitted receipt (CachingTierBlockedReceipt; per Artifact 5 §11.1 schema).
**Behavior:** Emits + persists CachingTierBlockedReceipt; surfaces user-facing notification "[document name] limited to local processing".
**Receipt:** CachingTierBlockedReceipt; durable per INV-V16-RETENTION-DURABLE-1.
**Implementation note:** Per Artifact 5 §11.1: receipt schema defined inline; persist via §3-style helper internally.
### §4.6 `emit_field_extraction_conflict(field: string, conflict_data: ExtractionConflict): void`
**Owner:** DOC10 / Artifact 4 UI layer.
**Caller:** Artifact 2 §4.2 `reconcile_extraction_value` (V4-J-2 metadata reconciliation).
**Returns:** void.
**Behavior:** Surfaces a user-facing reconciliation prompt: "extraction value differs from binding-asserted value for [field]; user resolution required".
**Receipt:** FieldExtractionConflictReceipt; durable.
**Implementation note:** Per HIGH-A2-3 R0.2 fix: ExtractionConflict schema includes parser_value, binding_value, llm_value with per-source confidence scores; UI surfaces all 3 with user choice.
### §4.7 `emit_metadata_reconciliation_required(...): void`
**Owner:** DOC10 / Artifact 4 UI layer.
**Caller:** Artifact 2 §4.2.
**Returns:** void.
**Behavior:** Variant of §4.6 for metadata-level (vs field-level) reconciliation.
**Receipt:** MetadataReconciliationRequiredReceipt; durable.
### §4.8 `emit_binding_metadata_overridden_by_parser_receipt(field: string, binding_value: any, parser_value: any): void`
**Owner:** DOC10 / Artifact 4 UI layer.
**Caller:** Artifact 5 §4.X parser metadata authority (per INV-K-METADATA-AUTHORITY-1).
**Returns:** void.
**Behavior:** When parser metadata authoritatively overrides binding-asserted metadata (per INV-K-METADATA-AUTHORITY-1), this receipt is emitted for audit transparency.
**Receipt:** BindingMetadataOverriddenByParserReceipt; durable.
### §4.9 `emit_share_link_revoke_envelope(share_token_id: string, revocation_params: ShareTokenRevocation): void`
**Owner:** Artifact 3 §4.3.10 kernel envelope emission (NOT pure UI; cross-listed here for cross-reference clarity).
**Caller:** Artifact 4 §5.2 `revoke_share_token` (post-persistence; per HIGH-A4-3 R0.2 clarification).
**Returns:** void.
**Behavior:** Emits the kernel envelope with effect_kind = "share_link_revoke" (Artifact 3 §4.3.10). Distinct from §3.3 persist_share_token_revocation: the persistence helper writes the entity, this helper writes the kernel effect.
**Receipt:** envelope receipt per Artifact 3 §1.4 envelope-replay store.
**Implementation note:** Per HIGH-A4-3: revocation flow is (a) persist_share_token_revocation (§3.3), (b) emit_share_link_revoke_envelope (this helper). Order matters; coding agents MUST persist row first, emit envelope second, in single transaction.
### §4.10 `emit_merge_candidate_for_user_review(candidate_pair: TopicMergeCandidate): void`
**Owner:** DOC10 / Artifact 4 UI layer.
**Caller:** Artifact 2 §5.3 `evaluate_topic_for_dedup` (INV-J-TOPIC-MERGE-1 per V4-J-4).
**Returns:** void.
**Behavior:** Surfaces a topic-merge candidate for user review (preserving INV-J-TOPIC-MERGE-1 manual-confirmation discipline).
**Receipt:** TopicMergeCandidateEmittedReceipt; durable.
### §4.11 `emit_contradiction_edge(...): void`
**Owner:** DOC10 / Artifact 4 UI layer + Artifact 3 contradiction-edge writer.
**Caller:** Artifact 2 §21.4 SemanticConflictPolicy `relationship_target_conflict → emit_contradiction_edge`.
**Returns:** void.
**Behavior:** Emits a ContradictionEdge in the knowledge graph + surfaces user notification.
**Receipt:** ContradictionEdgeEmittedReceipt; durable.
**Implementation note:** Combined kernel envelope + UI dispatch; coding agents MUST construct envelope FIRST.
### §4.12 `emit_collision_receipt_and_route_to_manual_review(collision: CollisionDetectionResult): void`
**Owner:** DOC10 / Artifact 4 UI layer.
**Caller:** Artifact 5 §10.3 `detect_hash_collision` (single_hash_collision_suspected branch).
**Returns:** void.
**Behavior:** Emits HashCollisionDetectedReceipt + routes to manual-review queue. Manual review is a host-session UI affordance per Artifact 4.
**Receipt:** HashCollisionDetectedReceipt; durable.
---
## §5. Cross-doc lookup helpers (~10 helpers)
Owner home: **cross-doc per V4 §0.4** (PropA / DOC10 / DOC72 / DOC25 / etc.).
These helpers are interface contracts to upstream docs in the V1.6 cross-doc forecast. Each helper has a canonical owner-doc and a forecast version (e.g., PropA R7+; DOC72 R5.74+). V1.6 release wave artifacts CONSUME these helpers; their implementations ship in the upstream docs separately from V1.6 release wave.
Common conformance rules for §5 helpers:
- All are read-only from V1.6 release wave perspective; they may have side effects in their owner-docs but those are out of V1.6 scope.
- Cross-doc interface contracts MUST be honored exactly per the forecast version specified.
- Coding agents implementing V1.6 release wave MUST NOT inline these helpers; the canonical implementation lives in the owner-doc.
- For bridge testing during V1.6 implementation, mock implementations are acceptable for cross-doc helpers; production implementations ship with the owner-doc.
### §5.1 `check_propa_authorization(artifact: SourceArtifact, scope: PropAScope): boolean`
**Owner:** PropA cross-doc (forecast: PropA R7+).
**Caller:** Artifact 5 §11.1 `dispatch_caching_tier` (Tier 1 sealed authorization check); Artifact 4 §X.X (cross-doc reference).
**Returns:** true iff PropA exposure policy authorizes outbound transmission of the artifact at the given scope.
**Behavior:** Per V4-§0.7-2 PropA exposure policy: PropA may pre-authorize specific scope tuples (e.g., `sealed_outbound`); without authorization, sealed content stays local.
**V1.6 implementation:** consume via PropA cross-doc interface; mock as `(_, _) => false` for V1.6 unit tests (default-deny).
**Cross-doc forecast:** PropA R7+ ships with PropAExposurePolicy + active-scope tracking.
### §5.2 `propa_authorization_active_for(artifact: SourceArtifact): PropAAuthorizationState`
**Owner:** PropA cross-doc (forecast: PropA R7+).
**Caller:** Artifact 5 §X (cross-doc query for current PropA state).
**Returns:** PropAAuthorizationState (per PropA R7+ canonical schema).
**Behavior:** Returns current authorization state for the artifact (which scopes are active, expiration, etc.).
**V1.6 implementation:** consume via PropA cross-doc; mock as `() => { active_scopes: [], expires_at: null }`.
### §5.3 `invalidate_session_local_cache_for_share_token(share_token_id: string): void`
**Owner:** Artifact 4 + EC session_context store (cross-doc per V4-I-3 NativeSessionScopeBinding caching).
**Caller:** Artifact 4 §5.2 `revoke_share_token`.
**Returns:** void.
**Behavior:** Invalidates session-local cache entries scoped to the revoked share token. Cache entries include AccessOverlay resolutions, SharedCorpusView snapshots, and session-context derivative caches.
**V1.6 implementation:** Implemented in EC session_context cache layer per V3.7 OBL-EC-NEW-SESSION-CONTEXT-01. Cache invalidation MUST be synchronous (revocation atomicity).
### §5.4 `invalidate_watermark_validity(share_token_id: string): void`
**Owner:** DOC24 (capability registry) + watermark subsystem (forecast: DOC24 R3.1+).
**Caller:** Artifact 4 §5.2 `revoke_share_token`.
**Returns:** void.
**Behavior:** Invalidates watermark validity tokens for downloaded copies tied to the share token. Per V1.6 watermark policy (Artifact 4 §6.X): downloaded copies have a validity check that fails post-revocation.
**V1.6 implementation:** consume via DOC24 watermark service.
### §5.5 `handle_active_session_disposition(session: ShareLinkSession, disposition: SessionDisposition): void`
**Owner:** EC session lifecycle subsystem (forecast: V3.7 OBL-EC-NEW-SESSION-LIFECYCLE-01) + Artifact 4 §6.
**Caller:** Artifact 4 §5.2 `revoke_share_token` (active-session disposition).
**Returns:** void.
**Behavior:** Per ShareTokenRevocation.active_session_disposition enum (per Artifact 4 §5.2):
- `"terminate_immediately"` → calls schedule_session_termination(0).
- `"grace_period"` → calls mark_session_expiring + schedule_session_termination(grace_window).
- `"continue"` → no-op (session continues per V1.6 default).
**V1.6 implementation:** Implemented in EC session lifecycle subsystem.
### §5.6 `mark_session_expiring(session_ref: SessionRef, reason_code: string): void`
**Owner:** EC session lifecycle subsystem.
**Caller:** Artifact 4 §5.2 (via §5.5) + general session-expiration paths.
**Returns:** void.
**Behavior:** Marks session as in expiring grace state; UI surfaces "session ending in N minutes" warning.
**V1.6 implementation:** Implemented in EC session lifecycle.
### §5.7 `schedule_session_termination(session_ref: SessionRef, delay_seconds: number): void`
**Owner:** EC session lifecycle subsystem.
**Caller:** Artifact 4 §5.2 (via §5.5) + general session-expiration paths.
**Returns:** void.
**Behavior:** Schedules session-termination task at NOW() + delay_seconds.
**V1.6 implementation:** Implemented in EC session lifecycle (cron-style scheduler or comparable).
### §5.8 `check_visibility_scope_permits(edge: CanonicalEntityEdge, session: SessionProfile): boolean`
**Owner:** EC database access layer + Artifact 3 §12 access overlay layer.
**Caller:** Artifact 2 §21.4 `resolve_same_as_edge_for_query` (INV-K-DEDUP-3).
**Returns:** true iff session has visibility into BOTH edge endpoints per access overlay rules.
**Behavior:** Per V3-K-7 + INV-K-DEDUP-1: same_as edges have visibility_scope_ref + firewall_id + allowed_principal_scope; check session against all three.
### §5.9 `re_evaluate_edge_against_current_policy(edge: CanonicalEntityEdge): EdgeReEvalResult`
**Owner:** EC database access layer + policy generation tracking.
**Caller:** Artifact 2 §21.4 `resolve_same_as_edge_for_query` (lazy re-evaluation per V4-K-INV-DEDUP-3).
**Returns:** `{ permitted_under_current_policy: boolean }`.
**Behavior:** Re-checks edge against the current policy_generation_id (not the edge's original generation). Per V4-K-INV-DEDUP-3: edges are not auto-invalidated when policy_generation advances; re-evaluation happens lazily at query time.
### §5.10 `is_external_agent(candidate_child_kind: AgentKind): boolean`
**Owner:** Artifact 4 §6.2 spawn validation logic.
**Caller:** Artifact 4 §6.2 `validate_subagent_spawn`.
**Returns:** true iff the agent kind is "external" (out-of-process via MCP, sandbox, etc.).
**Behavior:** Per V4-I-3 NativeSessionScopeBinding child_spawn_constraint enum: `internal_only` denies external agents.
**V1.6 implementation:** Inline at Artifact 4 §6.2; agent-kind taxonomy is a small enum (e.g., internal_specialist, external_mcp_agent, external_sandbox_agent). Coding agents MAY inline.
### §5.11 `parent_of(binding: NativeSessionScopeBinding): NativeSessionScopeBinding | undefined`
**Owner:** EC database access layer (parent walk).
**Caller:** Artifact 4 §6.2 `validate_subagent_spawn` (recursive parent lookup for inherit_parent_constraint).
**Returns:** parent NativeSessionScopeBinding or undefined if root.
**Behavior:** Reads `binding.parent_session_id` and resolves to NativeSessionScopeBinding.
**V1.6 implementation:** Inline; thin wrapper over §1.22 lookup_native_session_scope_binding.
### §5.12 `validate_subagent_spawn(parent: NativeSessionScopeBinding, candidate_child_kind: AgentKind): SpawnValidationResult`
**Owner:** Artifact 4 §6.2 (canonical home).
**Caller:** Artifact 4 §11.4 `dispatch_to_executor` (specialist sub-agent path).
**Returns:** `{ permitted: true } | { permitted: false; reason: string }`.
**Behavior:** Validates parent binding's fork_forbidden / max_spawn_depth / max_children / child_spawn_constraint per V4-I-3 spawn validation logic.
**Implementation note:** Cross-listed here as cross-doc reference because callers in Artifact 4 §11 reference the function from §6.2; canonical home is Artifact 4 §6.2 (declared inline; no DB query required at this level).
---
## §6. Specialized helpers (~32 helpers)
Owner home: **split per artifact** + EC kernel runtime.
These helpers are domain-specialized orchestration: kernel transaction primitives, binding fire dispatch, search router internals, simulation/replay, and access overlay resolution. Each helper has a specific home (within an artifact section or in the EC kernel runtime); the homes are listed per helper.
Common conformance rules for §6 helpers:
- These are NOT pure functions; they have side effects via kernel envelopes.
- Each helper has a specific home (artifact section or kernel runtime); the home is the canonical implementation site.
- Helpers in this section reference §1-§5 helpers (composition).
- Coding agents MUST implement each at the canonical home; cross-artifact callers reference via cross-section pointers.
### §6.A — Kernel orchestration (Artifact 3 home)
#### §6.A.1 `apply_effect(effect: KernelEffect, env: PBEOperationEnvelope): void`
**Owner:** Artifact 3 §2.3 (canonical home; per §2.3 dispatch).
**Caller:** Artifact 3 §2.3 main effect-application loop.
**Behavior:** Top-level effect dispatcher; switches on `effect.effect_kind` and calls per-kind apply_* helpers.
#### §6.A.2 `apply_node_write(effect: KernelEffect, env: PBEOperationEnvelope): void`
**Owner:** Artifact 3 §2.3 (declared at line 1295).
**Caller:** Artifact 3 §2.3 dispatcher.
**Behavior:** Per-effect-kind handler for `node_create`, `node_update`, `edge_create`, `edge_update`. Writes graph state per V4-A-1 effect_kind enum.
#### §6.A.3 `apply_inverse_effect(effect: KernelEffect, env: PBEOperationEnvelope): void`
**Owner:** Artifact 3 §5 (rollback runtime; declared at line 1831).
**Caller:** Artifact 3 §5 `apply_tier_2_rollback`.
**Behavior:** Applies the inverse_operation_kind effect for reversibility = `tier_2_inverse_recordable`. Per V4-A-1 reversibility classification.
#### §6.A.4 `construct_compensating_envelope(effect: KernelEffect, env: PBEOperationEnvelope): PBEOperationEnvelope`
**Owner:** Artifact 3 §5 (declared at line 1834).
**Caller:** Artifact 3 §5 `apply_tier_2_rollback`.
**Returns:** new PBEOperationEnvelope with compensating_operation_kind effects for reversibility = `tier_2_compensating_recordable`.
#### §6.A.5 `apply_primitive_effect_for_replay(effect: KernelEffect, env: PBEOperationEnvelope): void`
**Owner:** Artifact 3 §6 (replay runtime; declared at line 2237).
**Caller:** Artifact 3 §6 `apply_primitive_effects_for_replay` (LLM and non-LLM replay paths).
**Behavior:** Reuses §6.A.1 apply_effect logic for replay; explicit naming distinguishes replay-mode invocation from canonical write-path invocation. Per HIGH-A3-4 R0.2 fix: non-LLM replay path is fully specified.
#### §6.A.6 `compute_dry_run_effects(env_to_sim: PBEOperationEnvelope): KernelEffect[]`
**Owner:** Artifact 3 §11 (simulation runtime).
**Caller:** Artifact 3 §11 `simulate_envelope` (V4-A-SIM-COMPOSE).
**Returns:** computed effects WITHOUT applying them.
**Behavior:** Per V4-A-SIM-COMPOSE simulation discipline: pre-compute effects; presents to user for approval; no commit.
#### §6.A.7 `collect_visibility_classes(source_refs: NodeRef[]): VisibilityClass[]`
**Owner:** Artifact 3 §11 (line 3707).
**Caller:** Artifact 3 §11 simulation runtime; Artifact 3 §7 INV-A-TAINT-INFECTIOUS-1 lattice.
**Returns:** array of visibility classes for the source nodes.
**Behavior:** Composition: enumerates source nodes; reads `node.visibility_class`; returns array. Per INV-A-TAINT-INFECTIOUS-1: caller takes max via §2.3 lowest_in_lattice (or §2.6 max_visibility_class).
#### §6.A.8 `extract_output_node_visibility_class(env: PBEOperationEnvelope): VisibilityClass`
**Owner:** Artifact 3 §7 (declared at line 2577).
**Caller:** Artifact 3 §7 INV-A-TAINT-INFECTIOUS-1 enforcement.
**Returns:** the visibility class to set on the output node (per V4-AT-27 mixed-class context_packet).
#### §6.A.9 `extract_target_node_kind(env: PBEOperationEnvelope): NodeKind`
**Owner:** Artifact 3 §9 (line 3133).
**Caller:** Artifact 3 §9 INV-MVC-CU-1 enforcement.
**Returns:** the node_kind of the envelope's target node (per Artifact 1 §A NodeKind enum).
#### §6.A.10 `extract_target_node_payload(env: PBEOperationEnvelope): any`
**Owner:** Artifact 3 §9 (line 3135).
**Caller:** Artifact 3 §9 (CU validation).
**Returns:** the target node's payload from the envelope.
#### §6.A.11 `find_descendant_cus(target_cu_id: string): string[]`
**Owner:** Artifact 3 §8 (authority eager materialization; line 2892).
**Caller:** Artifact 3 §8 `process_authority_recompute_queue`.
**Returns:** array of CU IDs that depend (transitively) on target_cu_id.
**Behavior:** Graph traversal of CU input dependency edges per V4-AT-37 cu_authority materialized eagerly.
#### §6.A.12 `enqueue_recalculate_authority(target_cu_id: string, trigger_kind: string, ...): void`
**Owner:** Artifact 3 §8 (declared at line 2826).
**Caller:** Artifact 3 §8 + cascading authority recompute paths.
**Behavior:** Enqueues authority recompute request; per INV-A-AUTHORITY-EAGER-1.
#### §6.A.13 `process_authority_recompute_queue(): void`
**Owner:** Artifact 3 §8 (declared at line 2847).
**Caller:** Artifact 3 §8 (queue worker).
**Behavior:** Drains AUTHORITY_RECOMPUTE_QUEUE; calls compute_cu_authority for each.
#### §6.A.14 `compute_cu_authority(cu_id: string): number`
**Owner:** Artifact 3 §8 (declared at line 2858; cross-references Artifact 1 §15.X.7.7 V1.5.1 §28A formulas).
**Caller:** Artifact 3 §8.
**Returns:** authority score (per V1.5.1 §28A canonical formulas).
**Behavior:** Pure function over input CU authorities + edge weights; deterministic.
#### §6.A.15 `load_cu(cu_id: string): ConsolidatedUnderstanding`
**Owner:** EC database access layer (cross-listed in Artifact 3 §8).
**Caller:** Artifact 3 §8.
**Returns:** ConsolidatedUnderstanding entity per Artifact 1 §8.2.
#### §6.A.16 `load_input_cus(cu_id: string): ConsolidatedUnderstanding[]`
**Owner:** EC database access layer (cross-listed in Artifact 3 §8).
**Caller:** Artifact 3 §8.
**Returns:** array of input CUs feeding the target CU per cu_input_edges.
#### §6.A.17 `compute_authority(env_or_cu: PBEOperationEnvelope | ConsolidatedUnderstanding): number`
**Owner:** Artifact 3 §13.6 (binding outcome path; line 4999).
**Caller:** Artifact 3 §13.6 (V4-K-1 INV-K-OUTCOME-1).
**Returns:** authority score for the entity.
**Behavior:** Computes authority via V1.5.1 §28A formulas applied to envelope or CU.
#### §6.A.18 `apply_batch_review_operation(batch: BatchReviewOperation): void`
**Owner:** Artifact 3 §14.4 (declared at line 4716; per V3-AT-20 + V4-AT-PARTIAL).
**Caller:** Artifact 3 §14.4 batch operation runtime.
**Behavior:** Per-item application with INV-K-BATCH-PARTIAL-1; partial-failure semantics.
#### §6.A.19 `compute_earliest_required_phase(selectors: StructuralSelector[]): SelectorPhase`
**Owner:** Artifact 3 §13.8 (line 4293; per V4-K-2 selector_phase_available routing).
**Caller:** Artifact 3 §13.8 binding selector validation.
**Returns:** `pre_extraction | post_extraction` (V1.6 enum).
### §6.B — Simulation & preview (Artifact 3 home)
#### §6.B.1 `invoke_simulation_llm(prompt: string, policy: SimulationLLMPolicy): LLMOutput`
**Owner:** Artifact 3 §11 (line 3735).
**Caller:** Artifact 3 §11 simulation runtime.
**Returns:** LLM output for simulation (NOT for write-path invocation; per INV-G-SIM-1 simulation discipline).
**Behavior:** Routes to local LLM (Ollama) or sandboxed Tier 1 LLM per simulation policy. NEVER touches durable state; output stays in session_context.
#### §6.B.2 `construct_simulation_prompt(env_to_sim: PBEOperationEnvelope): string`
**Owner:** Artifact 3 §11 (line 3729).
**Caller:** Artifact 3 §11.
**Returns:** prompt string for simulation LLM.
**Behavior:** Composes envelope semantics into natural-language prompt.
#### §6.B.3 `classify_preview_kind(env_to_sim: PBEOperationEnvelope): PreviewKind`
**Owner:** Artifact 3 §11 (line 3746).
**Caller:** Artifact 3 §11.
**Returns:** PreviewKind enum (per V4-A-2 AuditReplayStrategy).
#### §6.B.4 `build_preview_payload(env_to_sim: PBEOperationEnvelope, llm_output: LLMOutput): any`
**Owner:** Artifact 3 §11 (line 3747).
**Caller:** Artifact 3 §11.
**Returns:** preview payload for user-facing simulation card.
#### §6.B.5 `estimate_capacity_cost(would_be_effects: KernelEffect[]): CapacityCost`
**Owner:** Artifact 3 §18 (capacity lease lifecycle; line 3750).
**Caller:** Artifact 3 §11 simulation runtime; §18 capacity tracking.
**Returns:** estimated capacity cost (token count, GPU seconds, etc.) per V4-A-COST-1.
### §6.C — Binding fire dispatch (Artifact 2 + Artifact 3 home)
#### §6.C.1 `dispatch_binding_fire_per_target_kind(binding: SourceBinding, source_event: SourceEvent): void`
**Owner:** Artifact 2 §17.5 (declared at line 3979).
**Caller:** Artifact 2 §17 binding fire main loop.
**Behavior:** Switches on `binding.target_kind` (per V4-K-1 BindingTargetKind axes); calls fire_with_* helper per target kind.
#### §6.C.2 `fire_with_membership_creation(binding: SourceBinding, source_event: SourceEvent): void`
**Owner:** Artifact 2 §17.5 + §20.5 (composition).
**Caller:** Artifact 2 §17.5 dispatcher (target_kind = "corpus_membership").
**Behavior:** Composes §3.11 create_corpus_membership + emits BindingFireReceipt.
#### §6.C.3 `fire_with_metadata_update(binding: SourceBinding, source_event: SourceEvent): void`
**Owner:** Artifact 2 §17.5 + §4 (LegalMetadataFieldValue).
**Caller:** target_kind = "metadata".
**Behavior:** Reconciles extracted metadata with binding-asserted metadata per INV-K-METADATA-AUTHORITY-1.
#### §6.C.4 `fire_with_relationship_candidate(binding: SourceBinding, source_event: SourceEvent): void`
**Owner:** Artifact 2 §17.5 + §15 (FilingRelationship / MotionChain).
**Caller:** target_kind = "filing_relationship".
**Behavior:** Emits relationship-candidate edge for user review.
#### §6.C.5 `fire_with_disposition_observation(binding: SourceBinding, source_event: SourceEvent): void`
**Owner:** Artifact 2 §17.5 + §14 (CourtDispositionObservation).
**Caller:** target_kind = "disposition".
**Behavior:** Emits CourtDispositionObservation; observation state lifecycle per Artifact 2 §14.2.
#### §6.C.6 `fire_with_extraction_task_only(binding: SourceBinding, source_event: SourceEvent): void`
**Owner:** Artifact 2 §17.5 + Artifact 5 §6 (ExtractionRunRecord).
**Caller:** target_kind = "extraction_only".
**Behavior:** Composes §3.10 create_extraction_run; no membership change.
### §6.D — Search router & access overlay (Artifact 4 home)
#### §6.D.1 `compute_session_access_set(session: SessionProfile, scope: SearchScope): AccessSet`
**Owner:** Artifact 4 §16.1 (canonical home; declared at line 3609).
**Caller:** Artifact 4 §15.4 INV-M-ACCESS-RANK-1 (forward-ref); §16.3 share-link search; multiple search paths.
**Behavior:** Computes per-entity access set per V4-B2-1 INV-B2-OVERLAY-RESOLUTION-1; returns `{permitted, permitted_preview_only, permitted_redacted, excluded}` per Artifact 4 §16.1 AccessSet schema.
#### §6.D.2 `enumerate_in_scope_entities(scope: SearchScope): Entity[]`
**Owner:** Artifact 4 §16.1 (line 3615).
**Caller:** Artifact 4 §16.1 `compute_session_access_set`.
**Returns:** baseline candidates per scope (corpus / filing-unit / segment / chunk).
#### §6.D.3 `resolve_overlays_for_entity(entity: Entity): AccessOverlay[]`
**Owner:** Artifact 4 §16.1 (line 3623).
**Caller:** Artifact 4 §16.1.
**Returns:** array of overlays applying to the entity (across all granularities).
#### §6.D.4 `resolve_overlays_per_inv_b2(overlays: AccessOverlay[], entity: Entity): AccessOverlay`
**Owner:** Artifact 3 §12.3 (canonical home per INV-B2-OVERLAY-RESOLUTION-1); Artifact 4 §16.1 read-time mirror.
**Caller:** Artifact 4 §16.1 + Artifact 3 §12.3 write-time enforcement.
**Returns:** the winning overlay per INV-B2-OVERLAY-RESOLUTION-1 (most-restrictive wins).
#### §6.D.5 `substitute_redacted_artifact(entity: Entity, winning: AccessOverlay): RedactedEntity`
**Owner:** Artifact 4 §16.1 (line 3645).
**Caller:** Artifact 4 §16.1 (`access_restriction = "redacted_only"` branch).
**Returns:** redacted artifact entity per Artifact 3 §12.6 RedactedAccessPolicy.
#### §6.D.6 `check_explicit_access_grant(session: SessionProfile, entity: Entity): boolean`
**Owner:** Artifact 4 §16.1 (line 3665).
**Caller:** Artifact 4 §16.1 (`access_restriction = "explicit_access_required"` branch).
**Returns:** true iff session has explicit grant.
#### §6.D.7 `check_corpus_access(corpus_ref: CorpusRef, session: SessionProfile): boolean`
**Owner:** Artifact 4 §14.2 (cross-firewall expansion blocked per INV-M-EXPANSION-ACCESS-1).
**Caller:** Artifact 4 §14.2 `compute_query_expansions`.
**Returns:** true iff session has access to the corpus.
#### §6.D.8 `any_overlay_with_ceremony_required(candidates: Entity[]): boolean`
**Owner:** Artifact 4 §16.1 (line 3684).
**Caller:** Artifact 4 §16.1 (defensive check; per V4-B2-2 access_ceremony_required removed).
**Returns:** true iff any candidate has access_ceremony_required overlay (defensive; should never be true post-V4-B2-2).
#### §6.D.9 `dispatch_executor(plan: UnifiedSearchPlan, assignment: ExecutorAssignment, ...): ExecutorResult`
**Owner:** Artifact 4 §11.4 (declared at line 2587).
**Caller:** Artifact 4 §10.X main search runtime.
**Behavior:** Per V4-M-5 multi-executor: dispatches to executor (primary_direct, doc18_legal_search_direct, memory_agent, document_intelligence_agent) per assignment; returns ExecutorResult.
#### §6.D.10 `spawn_specialist_sub_agent(...): NativeSessionScopeBinding`
**Owner:** Artifact 4 §11.4 (declared at line 2617).
**Caller:** Artifact 4 §11.4 dispatch (memory_agent / document_intelligence_agent path).
**Returns:** new NativeSessionScopeBinding for the spawned sub-agent.
**Behavior:** Composes §5.12 validate_subagent_spawn + §3.9 create_native_session_scope_binding.
#### §6.D.11 `spawn_openclaw_native_session(): SessionRef`
**Owner:** EC session lifecycle subsystem.
**Caller:** Artifact 4 §11.4 `spawn_specialist_sub_agent`.
**Returns:** new session_ref for sub-agent.
**Implementation note:** Cross-doc helper to EC session subsystem.
#### §6.D.12 `rank_within_access_set(candidates: Entity[], plan: UnifiedSearchPlan): RankedResults`
**Owner:** Artifact 4 §15 search router ranking layer.
**Caller:** Artifact 4 §15.X main ranking loop.
**Returns:** ranked results per INV-M-ACCESS-RANK-1 + INV-M-NEGATIVE-1.
#### §6.D.13 `compose_result_list(ranked: RankedResults): SearchResult[]`
**Owner:** Artifact 4 §15 ranking layer.
**Caller:** Artifact 4 §15.
**Returns:** final SearchResult array.
#### §6.D.14 `reciprocal_rank_fusion(executor_results: ExecutorResult[], k: number): SearchExecutionResult`
**Owner:** Artifact 4 §10.3 (line 2491; per V4-M-5).
**Caller:** Artifact 4 §10.3 `fuse_results` (rrf strategy).
**Returns:** fused SearchExecutionResult.
**Behavior:** Per V1.5.1 §28A.2 RRF formula with `k = RRF_K` (default 60).
#### §6.D.15 `weighted_sum_fusion(executor_results: ExecutorResult[], weights: number[]): SearchExecutionResult`
**Owner:** Artifact 4 §10.3 (line 2494).
**Caller:** Artifact 4 §10.3 (weighted_sum strategy).
#### §6.D.16 `concat_unique(executor_results: ExecutorResult[]): SearchExecutionResult`
**Owner:** Artifact 4 §10.3 (line 2503).
**Caller:** Artifact 4 §10.3 (executor_priority strategy fallback).
**Behavior:** Concatenates executor results; deduplicates by (source_artifact_id, filing_unit_id) tuple.
#### §6.D.17 `select_most_authoritative_version(versions: FilingUnitVersion[]): FilingUnitVersion`
**Owner:** Artifact 4 §15.5 (per INV-M-VERSION-AWARE-1 + V4-M-7).
**Caller:** Artifact 4 §15.5.
**Returns:** the most authoritative FilingUnitVersion per V4-O-2 legal_version_kind hierarchy.
#### §6.D.18 `group_by_filing_unit(results: SearchResult[]): Map<FilingUnitRef, SearchResult[]>`
**Owner:** Artifact 4 §15.5.
**Caller:** Artifact 4 §15.5 (FilingUnit-grouped result presentation).
**Returns:** grouping by FilingUnit for version-aware deduplication.
#### §6.D.19 `check_access_overlay_permits(entity: Entity, session: SessionProfile): boolean`
**Owner:** Artifact 4 §15.5 + Artifact 2 §16.4 + Artifact 2 §11.4.X (cross-listed).
**Caller:** Multiple read-side filtering paths.
**Returns:** boolean.
**Behavior:** Wrapper over §6.D.4 resolve_overlays_per_inv_b2 for boolean check.
#### §6.D.20 `check_visibility_permits(visibility_class: VisibilityClass, session: SessionProfile): boolean`
**Owner:** Artifact 2 §11.4.X (declared inline) + Artifact 4 §15.X (mirror).
**Caller:** Multiple read-side filtering paths.
**Returns:** true iff session has visibility into the class.
#### §6.D.21 `compute_query_expansions(query: Query, session: SessionProfile): QueryExpansionRecord[]`
**Owner:** Artifact 4 §14.2 (line 3202; V4-M-3 access-filtered).
**Caller:** Artifact 4 §14 query expansion runtime.
**Returns:** array of access-filtered expansion candidates.
#### §6.D.22 `compute_raw_expansion_candidates(query: Query): QueryExpansionCandidate[]`
**Owner:** Artifact 4 §14.2 (line 3206).
**Caller:** Artifact 4 §14.2 (pre-access-filter step).
**Returns:** raw candidates BEFORE access filtering.
### §6.E — Pure-binding helpers (Artifact 2 + Artifact 3 home)
#### §6.E.1 `evaluate_binding_filter(candidate: BindingCandidate, binding: SourceBinding): boolean`
**Owner:** Artifact 2 §19.4 (line 4336).
**Caller:** Artifact 2 §19.4 binding filter evaluation.
**Returns:** true iff candidate passes selector + content_type filter.
**Behavior:** Composes §2.11 matches_selector + §2.12 matches_content_type_filter.
#### §6.E.2 `validate_corpus_profile_storage(profile: CorpusProfile, write_set: NodeRef[]): ValidationResult`
**Owner:** Artifact 2 §3.2 (declared at line 836; INV-J-PROFILE-1 envelope-validation per MED-A2-4 R0.2 fix).
**Caller:** Artifact 2 §3.2 envelope-validation layer.
**Behavior:** Composes §1.9 lookup_target_node_kind for each write_ref; rejects writes that target nodes whose kind violates CorpusProfile.storage_constraint.
#### §6.E.3 `reconcile_extraction_value(field: string, parser_value: any, binding_value: any, llm_value?: any): ReconciliationResult`
**Owner:** Artifact 2 §4.2 (line 1016; per V4-J-2 metadata reconciliation).
**Caller:** Artifact 2 §4.2.
**Behavior:** Per V4-J-2 + INV-K-METADATA-AUTHORITY-1: parser wins; binding-asserted differs → emit conflict via §4.6.
#### §6.E.4 `filter_topics_by_share_link_visibility(topics: TopicAssignment[], session: SessionProfile): TopicAssignment[]`
**Owner:** Artifact 2 §5.2 (line 1195; INV-J-TOPIC-VIS-1).
**Caller:** Artifact 2 §5.2.
**Returns:** filtered topics per V4-J-3 + V4-J-3.5-K-3.6 8-value LegalProfileKind.
#### §6.E.5 `evaluate_topic_for_dedup(topic_a: TopicAssignment, topic_b: TopicAssignment, threshold: number): TopicMergeDecision`
**Owner:** Artifact 2 §5.3 (line 1277; INV-J-TOPIC-MERGE-1).
**Caller:** Artifact 2 §5.3.
**Returns:** dedup decision per V4-J-4 (threshold ≥0.93 for legal).
#### §6.E.6 `filter_pattern_library_for_session(library: PatternLibrary, session: SessionProfile): PatternLibrary`
**Owner:** Artifact 2 §6.2 (line 1490; INV-J-PATTERN-LIB-VIS-1).
**Caller:** Artifact 2 §6.2.
#### §6.E.7 `fork_corpus_profile(source_template_id: string, fork_params: ForkParams): CorpusProfileFork`
**Owner:** Artifact 2 §9.3 (line 1858; V4-J-FORK).
**Caller:** Artifact 2 §9.3.
**Behavior:** Composes §1.3 lookup_corpus_profile + §3.16 persist_corpus_profile_fork.
#### §6.E.8 `select_filing_unit_version(versions: FilingUnitVersion[], session: SessionProfile, query_intent: QueryIntent): FilingUnitVersion | undefined`
**Owner:** Artifact 2 §12.4 (line 2651; INV-O-VERSION-1).
**Caller:** Artifact 2 §12.4.
**Returns:** the version selected per V4-O-2 + version-aware ranking.
#### §6.E.9 `validate_ruling_disposition(disposition: RulingDisposition): ValidationResult`
**Owner:** Artifact 2 §13.4 (line 2867; INV-O-DISPOSITION-1).
**Caller:** Artifact 2 §13.4 envelope-validation.
**Behavior:** Composes §2.14 disposition_applies_to_subset + §2.15 is_scope_targets_empty + V4-O-4 mandatory scope_targets check.
#### §6.E.10 `format_disposition_citation(obs: CourtDispositionObservation): string`
**Owner:** Artifact 2 §14.2 (line 3109).
**Caller:** Artifact 2 §14.2.
**Returns:** formatted citation with supersession note if applicable.
**Behavior:** Composes §2.28 format_base_citation + §2.17 formatSupersessionNote + §1.25 lookup_observation.
#### §6.E.11 `render_citation(...): string`
**Owner:** Artifact 2 §16.1 (line 3548).
**Caller:** Artifact 2 §16 citation rendering.
**Behavior:** Composes §2.16 format_canonical_citation.
#### §6.E.12 `resolve_legal_evidence_posture(filing_unit: FilingUnit): LegalEvidencePosture`
**Owner:** Artifact 2 §16.2 (line 3606).
**Caller:** Artifact 2 §16.2.
**Returns:** LegalEvidencePosture per Artifact 2 §16.2 schema.
#### §6.E.13 `dedup_filing_units_post_access(candidates: FilingUnit[], session: SessionProfile): FilingUnit[]`
**Owner:** Artifact 2 §16.4 (line 3672; INV-K-DEDUP-2 per Artifact 4 §15.4).
**Caller:** Artifact 2 §16.4.
**Behavior:** Per INV-K-DEDUP-2: dedup runs AFTER access filter. Composes §6.D.19 check_access_overlay_permits + §6.E.14 dedup_by_filing_unit_id.
#### §6.E.14 `dedup_by_filing_unit_id(candidates: FilingUnit[]): FilingUnit[]`
**Owner:** Artifact 2 §16.4 (line 3680).
**Caller:** Artifact 2 §16.4.
**Returns:** deduplicated array (one entry per filing_unit_id).
#### §6.E.15 `resolve_filing_unit_for_new_artifact(identity: FilingUnitIdentity, metadata: ArtifactMetadata): FilingUnitResolution`
**Owner:** Artifact 2 §11.5.X (declared at line 2380; HIGH-A2-3 R0.2 decision tree).
**Caller:** Artifact 2 §11.5.X (canonical key resolution).
**Behavior:** Per HIGH-A2-3 R0.2 fix: 6-scenario decision tree (A-F).
**Returns:** `{resolution: ResolutionKind; filing_unit_id: string; new_version_kind?: string}`.
#### §6.E.16 `resolve_case_scope(case_ref: CaseRef, scope_kind: "exact" | "consolidated" | "all_alternates"): FilingUnit[]`
**Owner:** Artifact 2 §11.7 (declared at line ~2487; INV-O-CASE-RESOLUTION-1).
**Caller:** Artifact 2 §11.7.
**Behavior:** Composes §1.4 lookup_resolved_case_identity + §1.5 lookup_filing_units_by_exact_case_number + §1.6 lookup_filing_units_by_any_case_number per V4-O-3.
### §6.F — Group K eviction / health (Artifact 2 home)
#### §6.F.1 `validate_backfill_policy_change(...): ValidationResult`
**Owner:** Artifact 2 §22.3 (line 4953; INV-K-BACKFILL-1).
**Caller:** Artifact 2 §22.3.
#### §6.F.2 `compute_engagement_rate(contributions: CorpusBindingContribution[], decay_half_life_days?: number): number`
**Owner:** Artifact 2 §23.4 (R0.3 patch per XHIGH-4; canonical formula declared in cross-artifact audit).
**Caller:** Artifact 4 §17.3 `compute_binding_health_metrics`.
**Returns:** engagement rate ∈ [0, 1].
**Formula (per AUDIT_CROSS_ARTIFACT_R0.1.md XHIGH-4):**
```typescript
function compute_engagement_rate(
contributions: CorpusBindingContribution[],
decay_half_life_days: number = 30 // V1.6 default per
// DOC24_BINDING_ENGAGEMENT_DECAY_HALF_LIFE_DAYS
): number { // [0, 1]
// Per V2 patch L5 INV-K-HEALTH-1:
// "user-engagement-weighted contribution count"
//
// Definition: ratio of (decay-weighted user-interacted contributions)
// / (decay-weighted total contributions).
//
// Decay weight: exp(-ln(2) * age_days / decay_half_life_days)
if (contributions.length === 0) return 0;
let weighted_total = 0;
let weighted_engaged = 0;
const ln_2 = 0.6931471805599453;
for (const c of contributions) {
const age_days = (NOW() - c.contribution_event_at) / (86400 * 1000);
const decay_weight = Math.exp(-ln_2 * age_days / decay_half_life_days);
weighted_total += decay_weight;
const has_interaction = check_user_interaction(c.membership_id);
if (has_interaction) {
weighted_engaged += decay_weight;
}
}
return weighted_engaged / weighted_total;
}
```
**Implementation note:** `check_user_interaction` queries: search_result_clicks, document_open_events, cu_citation_edges, utility_signal_capture, share_link_share_events. See §6.F.3.
#### §6.F.3 `check_user_interaction(membership_id: string): boolean`
**Owner:** EC database access layer (composite query).
**Caller:** Artifact 2 §23.4 compute_engagement_rate (per §6.F.2).
**Returns:** true iff user has any of: clicked search result for the membership; opened document; cited document; marked helpful/unhelpful; shared via share-link.
**Behavior:** Composite read across 5 utility-signal stores per V4-I-6 UtilitySignalPolicy.
**Implementation note:** Backed by indexes on each utility-signal store.
#### §6.F.4 `compute_binding_health_metrics(binding_id: string, window_days?: number): BindingHealthMetrics`
**Owner:** Artifact 4 §17.3 (line 3883; INV-K-HEALTH-1).
**Caller:** Artifact 4 §17.3 binding health UI.
**Behavior:** Composes read_corpus_binding_contribution (DB) + §6.F.2 compute_engagement_rate.
### §6.G — Extraction pipeline (Artifact 5 home)
#### §6.G.1 `find_running_extractions_for_artifact(artifact_id: SourceArtifactRef): ExtractionRunRecord[]`
**Owner:** Artifact 5 §8.1 (line 2253; INV-EXT-6 in-flight cancellation).
**Caller:** Artifact 5 §8.1 `handle_document_artifact_version_changed`.
**Returns:** array of ExtractionRunRecords currently in `running` or `degraded` state for the artifact.
**Behavior:** Composes DB index query on `(filing_unit_ref, current_extraction_state)`.
**Implementation note:** Backed by extraction_run_records table indexed on artifact_id.
#### §6.G.2 `handle_document_artifact_version_changed(event: DocumentArtifactVersionChangedEvent): void`
**Owner:** Artifact 5 §8.1 (declared at line 2250; per V4-§0.6-IN-FLIGHT INV-EXT-6).
**Caller:** Artifact 5 §13 DocumentArtifactVersionChangedEvent emitter.
**Behavior:** Per INV-EXT-6: cancels running extractions; archives partial results as audit-only; creates new extraction run; emits user notification.
**Composition:** §6.G.1 find_running_extractions_for_artifact + kernel.record_extraction_state_transition + §3.8 archive_partial_results_for_audit_only + §3.10 create_extraction_run + §4.1 emit_user_notification.
#### §6.G.3 `process_extraction_queue(queue: ExtractionRunRecord[]): void`
**Owner:** Artifact 5 §X (line 1995; ExtractionStateMachine queue worker).
**Caller:** Artifact 5 ExtractionStateMachine canonical runtime.
#### §6.G.4 `process_single_extraction(run: ExtractionRunRecord): void`
**Owner:** Artifact 5 §X (line 1998).
**Caller:** Artifact 5 `process_extraction_queue`.
#### §6.G.5 `validate_degraded_state_metadata(...): ValidationResult`
**Owner:** Artifact 5 §X (line 2085; per INV-EXT-3).
**Caller:** Artifact 5 ExtractionStateMachine state-transition validation.
#### §6.G.6 `resolve_field_value(field: string, document_id: string): FieldResolution`
**Owner:** Artifact 5 §9.2 (declared at line 2404; per V4-§0.6-MVC-EXT INV-EXT-7).
**Caller:** Artifact 5 §9.2 + Artifact 4 §17.4 (cross-artifact via `artifact5.resolve_field_value`).
**Returns:** FieldResolution per Artifact 5 §9.2 schema.
**Behavior:** Composes §1.15 lookup_stale_memory + §1.16 lookup_active_re_extraction + §1.17 lookup_re_extraction_value.
#### §6.G.7 `validate_source_artifact_identity(artifact: SourceArtifact): ValidationResult`
**Owner:** Artifact 5 §X (line 775; INV-O-ARTIFACT-IDENTITY-1).
**Caller:** Artifact 5 SourceArtifact create envelope validation.
#### §6.G.8 `classify_cross_version_sharing(candidate_run: ExtractionRunRecord, existing_runs: ExtractionRunRecord[]): cross_version_sharing_basis`
**Owner:** Artifact 5 §6.5 (declared at line 1763).
**Caller:** Artifact 5 §6 deterministic-extraction sharing dispatch.
**Returns:** sharing basis or block reason (visibility_class / access_overlay / policy_generation).
**Behavior:** Composes §1.11 lookup_filing_part_text_hash + §1.13 lookup_visibility_class + §1.14 lookup_access_overlays + §6.G.9 access_overlays_equal.
#### §6.G.9 `access_overlays_equal(a: AccessOverlay[], b: AccessOverlay[]): boolean`
**Owner:** Artifact 5 §6.5 (line 1810).
**Caller:** Artifact 5 §6.5 `classify_cross_version_sharing`.
**Returns:** true iff both arrays contain the same set of overlays at the same granularities.
#### §6.G.10 `detect_hash_collision(candidate_artifact: SourceArtifact): CollisionDetectionResult`
**Owner:** Artifact 5 §10.3 (line 2603; per V4-§0.7-HASH).
**Caller:** Artifact 5 SourceArtifact create envelope.
**Returns:** CollisionDetectionResult per Artifact 5 §10.3 schema (CRIT-A5-1 R0.2 fix declared inline).
**Behavior:** Composes §1.18 lookup_artifacts_by_hash for each REQUIRED_HASH_KIND + §2.9 compute_intersection_across_kinds + §2.8 classify_collision_severity.
#### §6.G.11 `dispatch_caching_tier(artifact: SourceArtifact, requested_tier: "tier_1" | "tier_2" | "tier_3"): CachingDispatch`
**Owner:** Artifact 5 §11.1 (line 2737; INV-B2-CACHING-1 DOC25-side enforcement).
**Caller:** DOC25 caching pipeline (per A7 amendment).
**Behavior:** Composes §5.1 check_propa_authorization + §4.5 emit_caching_tier_blocked_receipt.
### §6.H — Misc (cross-artifact)
#### §6.H.1 `resolve_materialization_for_recipient(artifact: SourceArtifact, recipient_session: ShareLinkSession, shared_view: SharedCorpusView): RecipientMaterializationResolution`
**Owner:** Artifact 5 §5.3 (canonical home; declared at line 1354 per CRIT-A5-1 R0.2 fix).
**Caller:** Artifact 4 §16.3 `resolve_share_link_search_result` (cross-artifact via `lookup_source_artifact` + this helper).
**Returns:** RecipientMaterializationResolution (per Artifact 5 §5.3 schema).
**Behavior:** Composes §6.H.2 resolve_access_overlay_for_recipient.
#### §6.H.2 `resolve_access_overlay_for_recipient(artifact: SourceArtifact, recipient_session: ShareLinkSession): OverlayCheck`
**Owner:** Artifact 5 §5.3 (line 1389).
**Caller:** Artifact 5 §5.3 `resolve_materialization_for_recipient`.
**Returns:** overlay check result for recipient session per Artifact 4 §16 + Artifact 3 §12.
#### §6.H.3 `resolve_share_link_search_result(result: SearchResult, session: SessionProfile, shared_view: SharedCorpusView): ShareLinkSearchResult | null`
**Owner:** Artifact 4 §16.3 (line 3731).
**Caller:** Artifact 4 §16 share-link search runtime.
**Behavior:** Composes §6.D.1 compute_session_access_set + §1.30 lookup_source_artifact + §6.H.1 resolve_materialization_for_recipient.
#### §6.H.4 `resolve_field_at_read_time(field: string, document_id: string, session: SessionProfile): FieldResolution`
**Owner:** Artifact 4 §17.4 (line 3920).
**Caller:** Artifact 4 §17 read-path.
**Behavior:** Thin wrapper over Artifact 5 §9.2 §6.G.6 `resolve_field_value`. Per Artifact 5 §9 + Artifact 4 §17.4 cross-reference.
#### §6.H.5 `filter_stale_memories_at_read(results: SearchResult[]): SearchResult[]`
**Owner:** Artifact 4 §19.2 (line 4119).
**Caller:** Artifact 4 §19 search post-processing.
**Behavior:** Composes §1.28 lookup_derived_memory + INV-MVC-2 stale-marking filter. Stale memories WITH active re-extraction surface via §6.G.6 resolve_field_value with framing.
#### §6.H.6 `resolve_effective_shared_corpus_view(...): EffectiveSharedCorpusView`
**Owner:** Artifact 4 §4.3 (declared at line 1069; per V4-I-1 deny-wins).
**Caller:** Artifact 4 §4 SharedCorpusView resolution.
**Behavior:** Composes §1.32 lookup_shared_corpus_views + §2.1 most_restrictive_derived_memory + §2.2 most_restrictive_host_annotation + §2.3 lowest_in_lattice + §2.4 most_restrictive_temporal + §2.5 intersect_document_scopes.
#### §6.H.7 `filter_results_per_shared_corpus_view(results: SearchResult[], session: SessionProfile, target_ref: NodeRef): SearchResult[]`
**Owner:** Artifact 4 §4.2 (line 1008).
**Caller:** Artifact 4 §4 SharedCorpusView read-path.
**Behavior:** Composes §1.32 lookup_shared_corpus_views + §6.H.8 classify_result_surface.
#### §6.H.8 `classify_result_surface(result: SearchResult): ResultSurface`
**Owner:** Artifact 4 §4.2 (line 1021).
**Caller:** Artifact 4 §4.2 `filter_results_per_shared_corpus_view`.
**Returns:** ResultSurface per Artifact 4 §4.X (search-result / share-link / etc.).
#### §6.H.9 `derive_document_access_policy(host_session_ref: SessionRef): DocumentAccessPolicy`
**Owner:** Artifact 4 §5.1 (line 1158; per CRIT-A4-3 R0.2 fix).
**Caller:** Artifact 4 §5.1 `grant_share_link`.
**Returns:** DocumentAccessPolicy derived from host session per V4-I-1 deny-wins.
#### §6.H.10 `validate_state_transition(current: ProfileState, new_state: ProfileState): ValidationResult`
**Owner:** Artifact 4 §2.5 (line 650).
**Caller:** Artifact 4 §2.5 SessionProfile state-transition flow.
#### §6.H.11 `run_activation_gates(profile: SessionProfile): GateResult`
**Owner:** Artifact 4 §2.X (line 743).
**Caller:** Artifact 4 §2.X session activation runtime.
**Behavior:** Runs activation gates per Artifact 4 §2 SessionProfile activation.
#### §6.H.12 `validate_session_profile_for_search(...): ValidationResult`
**Owner:** Artifact 4 §15.X (line 3517).
**Caller:** Artifact 4 §15 search router entry.
**Behavior:** Validates session is in correct state for search.
#### §6.H.13 `validate_external_upload(upload_event: ExternalUploadEvent, session: SessionProfile): ValidationResult`
**Owner:** Artifact 4 §7.5 (line 1936; INV-I-UPLOAD-1).
**Caller:** Artifact 4 §7.5 quarantine path.
**Behavior:** Composes §1.35 lookup_external_upload_file_safety_controls + §6.H.14 sniff_mime + §6.H.15 attempt_strip_active_content + §1.19 lookup_existing_artifact_by_hash.
#### §6.H.14 `sniff_mime(bytes: Uint8Array): string`
**Owner:** DOC25 V2.0+ (per A8 amendment; ingestion-side primitive).
**Caller:** Artifact 4 §7.5; Artifact 5 ingestion paths.
**Returns:** sniffed MIME type from bytes.
**V1.6 implementation:** Implemented in DOC25 ingestion subsystem per V4-I-UPLOAD-1.
#### §6.H.15 `attempt_strip_active_content(upload_event: ExternalUploadEvent): UploadEvent`
**Owner:** DOC25 V2.0+ (per A8 amendment).
**Caller:** Artifact 4 §7.5.
**Returns:** upload event with active content stripped (e.g., script tags removed from PDF).
**V1.6 implementation:** DOC25 ingestion.
#### §6.H.16 `has_active_content(upload_event: ExternalUploadEvent): boolean`
**Owner:** DOC25 V2.0+.
**Caller:** Artifact 4 §7.5.
#### §6.H.17 `is_archive(upload_event: ExternalUploadEvent): boolean`
**Owner:** DOC25 V2.0+.
**Caller:** Artifact 4 §7.5.
#### §6.H.18 `compute_decompression_ratio(upload_event: ExternalUploadEvent): number`
**Owner:** DOC25 V2.0+.
**Caller:** Artifact 4 §7.5 (zip-bomb guard).
#### §6.H.19 `compute_decompressed_size(upload_event: ExternalUploadEvent): number`
**Owner:** DOC25 V2.0+.
**Caller:** Artifact 4 §7.5.
#### §6.H.20 `dispatch_captured_signal(signal: UtilitySignal): void`
**Owner:** Artifact 4 §7.1 (line 1723).
**Caller:** Artifact 4 §7 utility signal capture.
#### §6.H.21 `resolve_denial_message_text(reason_code: string, recipient_session: SessionProfile): string`
**Owner:** Artifact 4 §15.X (line 1833; V4-I-DENIAL-1).
**Caller:** Artifact 4 §15.X denial messaging.
**Behavior:** Composes §1.36 lookup_reason_code + §6.H.22 resolve_recipient_visibility.
#### §6.H.22 `resolve_recipient_visibility(reason_code: string): RecipientVisibility`
**Owner:** Artifact 4 §15.X (line 2252).
**Caller:** Artifact 4 §15.X.
**Returns:** RecipientVisibility per V4-I-DENIAL-1 reason-code policy.
#### §6.H.23 `validate_session_binding_agreement(...): ValidationResult`
**Owner:** Artifact 4 §6.X (line 1637).
**Caller:** Artifact 4 §6 session binding agreement validation.
#### §6.H.24 `format_no_results_answer(...): string`
**Owner:** Artifact 4 §15.X (line 3293).
**Caller:** Artifact 4 §15 no-results path.
#### §6.H.25 `classify_completeness(...): SearchCompletenessKind`
**Owner:** Artifact 4 §15.X (line 3328).
**Caller:** Artifact 4 §15 completeness classification.
#### §6.H.26 `emit_search_coverage_receipts(plan: UnifiedSearchPlan, search_run: SearchExecutionResult): void`
**Owner:** Artifact 4 §13.X (line 3051).
**Caller:** Artifact 4 §13.
**Behavior:** Composes §3.4 persist_coverage_receipt_internal + §3.5 persist_coverage_receipt_visible + §6.H.27 construct_full_coverage_receipt.
#### §6.H.27 `construct_full_coverage_receipt(search_run: SearchExecutionResult): SearchCoverageReceiptInternal`
**Owner:** Artifact 4 §13.X (line 3056).
**Caller:** Artifact 4 §13.X `emit_search_coverage_receipts`.
---
## §7. Helper-home audit checklist + Landing Matrix integration
### §7.1 Coverage check against AUDIT_CROSS_ARTIFACT_R0.1.md XCRIT-1
The cross-artifact audit XCRIT-1 enumerates ~82 phantom helpers in 6 categories. This appendix declares canonical homes for each. Coverage cross-check:
```text
Category from XCRIT-1 XCRIT-1 count Covered in § Count this appendix
─────────────────────────────────────────────────────────────────────────────────────────
DB-layer lookups ~25 §1 36
Pure functions ~15 §2 29
Persistence helpers ~12 §3 17
Notification / event emission ~8 §4 12
Cross-doc lookups ~10 §5 12
Specialized helpers ~12 §6 ~80 (across A-H)
─────────────────────────────────────────────────────────────────────────────────────────
TOTAL ~82 — ~186
```
Note: This appendix's count exceeds XCRIT-1's enumeration because the cross-artifact audit listed primary helpers per category; this appendix expands to include composition helpers and per-effect dispatchers (e.g., apply_node_write, apply_inverse_effect, fire_with_*_creation per binding target kind). The thoroughness aligns with architect's "no shortcuts" rule.
Per-artifact coverage verification:
```text
Artifact Audit phantom-helper count Covered Status
──────────────────────────────────────────────────────────────
Artifact 2 ~28 (CRIT-A2-2) ✓ All §11.5/§13.4/§14.2/§16.1/§16.4/§17.5/§19.4/§20.5/§21.4/§22.3/§23.3 helpers covered.
Artifact 3 ~12 (mostly inline) ✓ §6.A apply_*/load_cu/find_descendant_cus/compute_cu_authority + §6.B simulation helpers covered.
Artifact 4 ~32 (HIGH-A4-1) ✓ §10.3 fusion + §16.1 access overlay + §11.4 dispatch + §17 binding read + §15 ranking + §19 stale memory + §6.2 spawn + §7.5 upload + §5 share-link helpers covered. [R0.2 PATCH per CSA extraction: §18 CSA removed; §18 is now session-orientation injection deferred to DOC72.]
Artifact 5 ~22 (MED-A5-5) ✓ §6.5 cross-version + §7-9 extraction FSM + §10.3 hash collision + §11.1 caching tier helpers covered.
──────────────────────────────────────────────────────────────
```
### §7.2 Per-artifact callout integration
Each artifact's R0.3 patch (or R0.4 for Artifact 1) MUST add a helper-homes cross-reference note in §1.X (Drafting Summary) pointing to this appendix:
```text
Artifact 1 R0.4 §1.X (Drafting Summary helper-homes note):
"All phantom helpers referenced in pseudocode resolve via
DOC73_V1_6_HELPER_HOMES_R0.1.md. See helper-home appendix
§6.A (kernel orchestration), §6.B (simulation/preview),
§6.D-§6.H (cross-cutting search/access/extraction)."
Artifact 2 R0.3 §1.X note (similar):
"All phantom helpers in §3.2/§4.2/§5.2/§5.3/§5.4/§6.2/§9.3/
§11.5/§11.7/§12.4/§13.4/§14.2/§16.1/§16.2/§16.4/§17.5/
§19.4/§20.5/§21.4/§22.3/§23.3 resolve via
DOC73_V1_6_HELPER_HOMES_R0.1.md §1-§6."
Artifact 3 R0.2 §1.X note:
"Kernel orchestration helpers per §6.A; simulation/preview
helpers per §6.B; cross-references per §6.D-§6.H."
Artifact 4 R0.2 §1.X note:
"Search router/access overlay/binding-read helpers per §6.D-§6.H;
share-link grant/revoke flow helpers per §6.H.9 + §3.2 + §3.3."
Artifact 5 R0.3 §1.X note:
"Extraction FSM/hash collision/caching tier helpers per §6.G
+ §6.H.1-§6.H.2 (recipient resolution)."
```
### §7.3 Landing Matrix integration
This appendix occupies a single Landing Matrix entry across the V1.6 release wave:
```text
Row HELPER.1 DOC73_V1_6_HELPER_HOMES_R0.1.md (this document)
Owner: V1.6 release wave handoff package
V4 patch refs: implicit per V4-§0.4-1 owner-doc
adapter mapping (Step 9 deliverable
for XCRIT-1)
AT refs: V4-AT-40 (INV-V16-NO-LOCAL-SCHEMA-1
compliance)
Cross-doc deps: V4 §0.4 owner-doc ownership
distribution; V3.7 OBL-EC-NEW-*
row family for persistence helpers
Status: R1.0 freeze deliverable (R0.1 ships with
V1.6 release wave handoff)
```
### §7.4 Implementation-handoff guidance
For coding agents implementing V1.6 release wave:
```text
PHASE 1 — Per-artifact implementation kick-off:
1. Read DOC73_V1_6_HELPER_HOMES_R0.1.md §0 (purpose) and the
§s relevant to the artifact under implementation.
2. Identify the helper homes for every helper referenced by
the artifact's pseudocode.
3. For helpers in §1 (DB-layer): coordinate with EC Core
Addendum A V3.5+ implementation; if those layers are not
yet built, mock with deterministic in-memory implementations
that match the appendix signature.
4. For helpers in §2 (pure functions): inline declare in the
artifact module; signature MUST match this appendix.
5. For helpers in §3 (persistence): coordinate with EC
persistence runtime; pass-through via kernel envelope per
INV-15.7.8.
6. For helpers in §4 (notification/UI): mock with no-op
implementations during artifact unit testing; production
wires to DOC10 / Q Dashboard at integration test time.
7. For helpers in §5 (cross-doc): mock with deterministic
stubs; production implementations ship with upstream docs.
8. For helpers in §6 (specialized): implement at the canonical
home (specified per helper); cross-artifact callers pass
through.
PHASE 2 — Cross-artifact integration testing:
1. Verify helper signatures match this appendix EXACTLY.
2. Verify behavior contracts honored (retention class,
durability, error modes).
3. Verify INV-V16-NO-LOCAL-SCHEMA-1 compliance: no helper
has 2 canonical implementations.
PHASE 3 — Production rollout:
1. Cross-doc helpers (§5) must have production
implementations from upstream docs available.
2. UI helpers (§4) must have DOC10 / Q Dashboard
implementations available.
3. EC Core Addendum A V3.5+ database access layer (§1)
must be available.
4. EC persistence runtime (§3) must be available.
ROLLBACK / ITERATION:
If a helper signature needs to change post-V1.6 release wave,
coding agent triggers a R0.X amendment to this appendix.
Architect Will reviews the change. If approved, the appendix
is patched and downstream artifacts are notified via cross-
reference update.
```
### §7.5 Step 9 deliverable status (per AUDIT_CROSS_ARTIFACT_R0.1.md)
This appendix discharges:
- **XCRIT-1** (helper-home appendix): ✓ COMPLETE in R0.1.
- **CRIT-A2-2** (~28 phantom helpers in Artifact 2): ✓ All Artifact 2 phantom helpers have canonical homes per §1-§6.
- **HIGH-A4-1** (~32 phantom helpers in Artifact 4): ✓ All Artifact 4 phantom helpers have canonical homes per §1-§6.
- **MED-A5-5** (~22 phantom helpers in Artifact 5): ✓ All Artifact 5 phantom helpers have canonical homes per §1-§6.
- Partial discharge for **XHIGH-4** `compute_engagement_rate` formula spec: ✓ Formula declared at §6.F.2 (canonical home Artifact 2 R0.3 §23.4 per cross-artifact patch).
- Partial discharge for **XHIGH-3** ECFHeaderParserOutput.ecf_annotations: NOT discharged here; cross-artifact patch lives in Artifact 5 R0.3 §4.2 (separate R0.3 deliverable).
- Partial discharge for **XHIGH-2** Ref types move from Artifact 2 §0.7 to Artifact 1 §A: NOT discharged here; cross-artifact patch lives in Artifact 1 R0.4 §A (separate R0.4 deliverable).
Remaining Step 9 deliverables for R1.0 freeze:
- **XHIGH-1** Cross-artifact end-to-end worked examples (PACER ingestion + court-amended cascade): ~600-1000 lines in Artifact 1 R0.4 §B.
- **XHIGH-3** ECFHeaderParserOutput.ecf_annotations: ~25 lines in Artifact 5 R0.3 §4.2.
- **XHIGH-2** Ref types appendix move: ~50 lines in Artifact 1 R0.4 §A; cross-reference in Artifact 2 R0.3 §0.7.
- **XMED-1** Architect triage of 47 BUILD_QUESTIONS Tier B items (architect work, ~1-2 days).
### §7.6 R0.X amendment policy
Future patches to this appendix follow Path B-minus discipline:
- **R0.2 patch** (V1.6 implementation): if coding agents discover phantom helpers not enumerated here, add to appendix; bump to R0.2.
- **R0.3 patch** (V1.6.1 release wave): if V1.6.1 introduces new helpers, extend appendix.
- **R1.0 freeze** (V1.7+ candidates): freeze appendix shape; major changes routed through V1.7 cycle.
- **CRITICAL drift** (helper signature mismatch in production): emergency R0.X patch + audit-log entry + architect review.
### §7.7 Drafting Summary
```text
Document: DOC73_V1_6_HELPER_HOMES_R0.1.md
Length: ~~ approximate lines pending final count
Helpers declared: ~186 (across §1-§6)
Sections: 7 (§0 purpose; §1-§6 by category;
§7 audit checklist)
V4 patch refs: V4-§0.4-1 (DOC24 ownership);
V4-§0.4-2 (Mechanism 4 reclass);
V4-A-1 (effect_kind enum);
V4-I-DENIAL-1 (reason-code namespace);
V4-I-3 (NSB expansion);
V4-K-FANOUT (binding fan-out);
V4-K-INV-DEDUP-3 (lazy re-evaluation);
V4-M-3 (access-filtered expansion);
V4-M-5 (multi-executor);
V4-O-3 (ResolvedCaseIdentity);
V4-O-4 (mandatory scope_targets);
V4-O-5 (RulingDispositionPolarity);
V4-§0.6-IN-FLIGHT (INV-EXT-6);
V4-§0.6-MVC-EXT (INV-EXT-7);
V4-§0.7-HASH (multi-hash discipline);
V4-J-FORK (CorpusProfileFork)
AT refs: V4-AT-40 (INV-V16-NO-LOCAL-SCHEMA-1
compliance check)
Cross-doc deps: EC Core Addendum A V3.5+;
DOC25 V2.0+ (per A1-A9 amendments
in Artifact 5 §1.2);
DOC72 R5.74+;
DOC24 R3.1+;
PropA R7+;
DOC10 Q Dashboard UI layer
INV ownership: This document does NOT own any INVs;
it implements/composes existing INVs.
Cross-references for callers:
INV-15.7.8 (Artifact 3 §20.1);
INV-15.7.9 (Artifact 3 §20.2);
INV-V16-RETENTION-DURABLE-1 (Artifact 1 §19.4);
INV-V16-NO-LOCAL-SCHEMA-1 (Artifact 1 §19.2);
INV-A-TAINT-INFECTIOUS-1 (Artifact 3 §7.1);
INV-K-MANIFEST-DURABLE-1 (Artifact 3 §15.2);
INV-K-MEMBERSHIP-EXTRACTION-1 (Artifact 2 §20.5);
INV-K-METADATA-AUTHORITY-1 (Artifact 5 §4.1);
INV-K-DEDUP-1/2/3 (Artifact 2 §21);
INV-O-FILING-PART-VIS-1 (Artifact 2 §11.4.X);
INV-EXT-1 through INV-EXT-7 (Artifact 5 §7-§9);
INV-B2-OVERLAY-RESOLUTION-1 (Artifact 3 §12.3);
INV-B2-CACHING-1 (Artifact 3 §12.5);
INV-I-* (Artifact 4 §3-§7);
INV-J-* (Artifact 2 §3-§9);
INV-M-* (Artifact 4 §13-§20);
INV-N-* (Artifact 1 §16);
INV-MVC-1/2/3/CU-1 (Artifact 1 §15.X +
Artifact 3 §9-§10).
Path B-minus alignment: ✓ COMPLETE — discharges all phantom helper
audit findings (CRIT-A2-2, HIGH-A4-1,
MED-A5-5) per architect Path B-minus.
Cross-artifact specific items (XHIGH-2/3/4)
still require separate R0.3/R0.4 patches
to Artifact 1, 2, 5.
```
---
## §8. Closing notes
Per architect Path B-minus + AUDIT_CROSS_ARTIFACT_R0.1.md XCRIT-1: this appendix is a R1.0 freeze blocker discharged at R0.1.
The V1.6 release wave is **NOT YET READY for R1.0 freeze**, but is structurally sound and ~85% complete after this R0.1 ships. Remaining work concentrated in:
1. **Cross-artifact end-to-end worked examples** (XHIGH-1; ~600-1000 lines in Artifact 1 R0.4 §B).
2. **Cross-artifact schema patches** (XHIGH-2/3/4; ~125 lines across Artifact 1 R0.4, Artifact 2 R0.3, Artifact 5 R0.3).
3. **Architect triage of 47 BUILD_QUESTIONS Tier B items** (architect work; ~1-2 days).
After those three deliverables ship and architect triage completes, V1.6 release wave is **READY FOR R1.0 FREEZE**.
R0.X amendment policy applies post-R1.0 freeze (per §7.6).
— End of DOC73_V1_6_HELPER_HOMES_R0.1.md —