From 6e10a87cf8c0f090854672a7453cf20fb2d416e9 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 17:56:01 +0900 Subject: [PATCH 01/57] test(naming): define result application semantic contract --- ...test_result_application_naming_contract.py | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 tests/test_result_application_naming_contract.py diff --git a/tests/test_result_application_naming_contract.py b/tests/test_result_application_naming_contract.py new file mode 100644 index 000000000..18520679d --- /dev/null +++ b/tests/test_result_application_naming_contract.py @@ -0,0 +1,54 @@ +"""Naming-contract regressions for checkpointed result application.""" + +from dataclasses import fields +from inspect import signature + +from pg_llm_batch import result_application as result_application + + +def test_result_application_internal_signatures_use_semantic_names() -> None: + """Owned helpers describe checkpointed-result semantics instead of generic values.""" + assert tuple(signature(result_application.ResultApplicationError.__init__).parameters) == ( + "self", + "application_phase", + ) + assert tuple(signature(result_application._redacted_validation_error).parameters) == ( + "field_name", + "validation_reason", + ) + assert tuple(signature(result_application._validate_item_and_effect).parameters) == ( + "checkpointed_record", + "record_effect", + ) + assert tuple( + signature(result_application._apply_checkpointed_record_in_transaction).parameters + ) == ( + "transaction_cursor", + "checkpoint_store", + "consumer_name", + "checkpointed_record", + "record_effect", + ) + + +def test_result_application_outcome_uses_semantic_fields_with_legacy_accessors() -> None: + """The domain result owns semantic fields while legacy attribute reads stay compatible.""" + assert {field.name for field in fields(result_application.ResultApplicationOutcome)} == { + "record_applied", + "result_checkpoint", + } + assert isinstance(result_application.ResultApplicationOutcome.applied, property) + assert isinstance(result_application.ResultApplicationOutcome.checkpoint, property) + + +def test_legacy_public_function_remains_an_explicit_compatibility_adapter() -> None: + """Existing keyword callers retain the released parameter contract at the ACL boundary.""" + assert tuple( + signature(result_application.apply_checkpointed_result_in_transaction).parameters + ) == ( + "cursor", + "checkpoint_store", + "consumer_name", + "item", + "apply_record", + ) From 6e12edbe7e320ae4d3396837d4b3517808f2c2bc Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 17:57:17 +0900 Subject: [PATCH 02/57] refactor(results): isolate semantic application identifiers --- pg_llm_batch/result_application.py | 313 ++++++++++++++++++----------- 1 file changed, 199 insertions(+), 114 deletions(-) diff --git a/pg_llm_batch/result_application.py b/pg_llm_batch/result_application.py index 631263cdd..8fcdef6b7 100644 --- a/pg_llm_batch/result_application.py +++ b/pg_llm_batch/result_application.py @@ -29,21 +29,63 @@ class ResultApplicationError(PgLlmBatchError): """Report one bounded failure while applying a checkpointed result.""" - def __init__(self, phase: str) -> None: + def __init__(self, application_phase: str) -> None: """Create fixed diagnostic evidence for one application phase.""" super().__init__( message="Checkpointed result application failed", error_code="RESULT_APPLICATION_ERROR", - details={"phase": phase}, + details={"phase": application_phase}, ) -@dataclass(frozen=True) +@dataclass(frozen=True, init=False) class ResultApplicationOutcome: - """Describe whether one local record effect was newly applied.""" + """Describe whether one local record effect was newly applied. - applied: bool - checkpoint: BatchResultCheckpoint + ``record_applied`` and ``result_checkpoint`` are the package-owned semantic + fields. The historical ``applied`` and ``checkpoint`` constructor keywords + and read-only properties remain as a compatibility boundary for released + callers. + """ + + record_applied: bool + result_checkpoint: BatchResultCheckpoint + + def __init__( + self, + record_applied: bool | None = None, + result_checkpoint: BatchResultCheckpoint | None = None, + *, + applied: bool | None = None, + checkpoint: BatchResultCheckpoint | None = None, + ) -> None: + """Normalize semantic or legacy outcome arguments without ambiguity.""" + if record_applied is not None and applied is not None: + raise TypeError("use record_applied or legacy applied, not both") + if result_checkpoint is not None and checkpoint is not None: + raise TypeError("use result_checkpoint or legacy checkpoint, not both") + normalized_record_applied = ( + record_applied if record_applied is not None else applied + ) + normalized_result_checkpoint = ( + result_checkpoint if result_checkpoint is not None else checkpoint + ) + if normalized_record_applied is None: + raise TypeError("record_applied is required") + if normalized_result_checkpoint is None: + raise TypeError("result_checkpoint is required") + object.__setattr__(self, "record_applied", normalized_record_applied) + object.__setattr__(self, "result_checkpoint", normalized_result_checkpoint) + + @property + def applied(self) -> bool: + """Return the legacy applied flag for source compatibility.""" + return self.record_applied + + @property + def checkpoint(self) -> BatchResultCheckpoint: + """Return the legacy checkpoint attribute for source compatibility.""" + return self.result_checkpoint class _ResultApplicationCursor: @@ -102,83 +144,195 @@ def fetchall(self, *args: Any, **kwargs: Any) -> Any: return self.__cursor.fetchall(*args, **kwargs) -def _redacted_validation_error(field: str, reason: str) -> ValidationError: +def _redacted_validation_error( + field_name: str, + validation_reason: str, +) -> ValidationError: """Build a validation error without retaining caller-controlled content.""" - return ValidationError(field=field, value="", reason=reason) + return ValidationError( + field=field_name, + value="", + reason=validation_reason, + ) -def _checkpoint_primitive_type_error(checkpoint: BatchResultCheckpoint) -> str | None: +def _checkpoint_primitive_type_error( + result_checkpoint: BatchResultCheckpoint, +) -> str | None: """Return the first checkpoint field whose primitive type can execute behavior.""" - for field in ( + for checkpoint_field_name in ( "batch_id", "endpoint_alias", "file_kind", "file_id", "prefix_sha256", ): - if type(getattr(checkpoint, field)) is not str: - return field - for field in ( + if type(getattr(result_checkpoint, checkpoint_field_name)) is not str: + return checkpoint_field_name + for checkpoint_field_name in ( "schema_version", "file_line_number", "batch_line_count", "record_count", ): - if type(getattr(checkpoint, field)) is not int: - return field + if type(getattr(result_checkpoint, checkpoint_field_name)) is not int: + return checkpoint_field_name return None def _validate_item_and_effect( - item: Any, - apply_record: Any, + checkpointed_record: Any, + record_effect: Any, ) -> CheckpointedBatchResultRecord: """Validate the local application boundary before store or callback work.""" - if type(item) is not CheckpointedBatchResultRecord: + if type(checkpointed_record) is not CheckpointedBatchResultRecord: raise _redacted_validation_error( "item", "must be an exact checkpointed batch result record" ) - checkpoint = item.checkpoint - if type(checkpoint) is not BatchResultCheckpoint: + result_checkpoint = checkpointed_record.checkpoint + if type(result_checkpoint) is not BatchResultCheckpoint: raise _redacted_validation_error( "item.checkpoint", "must be an exact batch result checkpoint" ) - checkpoint_field = _checkpoint_primitive_type_error(checkpoint) - if checkpoint_field is not None: + checkpoint_field_name = _checkpoint_primitive_type_error(result_checkpoint) + if checkpoint_field_name is not None: raise _redacted_validation_error( - f"item.checkpoint.{checkpoint_field}", + f"item.checkpoint.{checkpoint_field_name}", "must use an exact built-in primitive type", ) - if type(item.batch_id) is not str: + if type(checkpointed_record.batch_id) is not str: raise _redacted_validation_error( "item.batch_id", "must be an exact built-in string" ) - if type(item.file_kind) is not str: + if type(checkpointed_record.file_kind) is not str: raise _redacted_validation_error( "item.file_kind", "must be an exact built-in string" ) - if not callable(apply_record): + if not callable(record_effect): raise _redacted_validation_error("apply_record", "must be callable") - static_call = inspect.getattr_static(apply_record, "__call__", None) + static_call = inspect.getattr_static(record_effect, "__call__", None) if isinstance(static_call, (staticmethod, classmethod)): static_call = static_call.__func__ - if inspect.iscoroutinefunction(apply_record) or inspect.iscoroutinefunction( + if inspect.iscoroutinefunction(record_effect) or inspect.iscoroutinefunction( static_call ): raise _redacted_validation_error( "apply_record", "must complete synchronously in the caller transaction" ) - if item.batch_id != checkpoint.batch_id: + if checkpointed_record.batch_id != result_checkpoint.batch_id: raise _redacted_validation_error( "item.batch_id", "must match the checkpoint batch identity" ) - if item.file_kind != checkpoint.file_kind: + if checkpointed_record.file_kind != result_checkpoint.file_kind: raise _redacted_validation_error( "item.file_kind", "must match the checkpoint file kind" ) - if type(item.record) is not dict: + if type(checkpointed_record.record) is not dict: raise _redacted_validation_error("item.record", "must be an exact JSON object") - return item + return checkpointed_record + + +def _apply_checkpointed_record_in_transaction( + transaction_cursor: Any, + checkpoint_store: Any, + consumer_name: str, + checkpointed_record: CheckpointedBatchResultRecord, + record_effect: Callable[[Any, Mapping[str, Any]], None], +) -> ResultApplicationOutcome: + """Apply one semantic checkpointed record within the caller transaction.""" + validated_record = _validate_item_and_effect(checkpointed_record, record_effect) + + checkpoint_load_failure: ResultApplicationError | None = None + previous_checkpoint: BatchResultCheckpoint | None = None + try: + previous_checkpoint = checkpoint_store.load_in_transaction( + transaction_cursor, + consumer_name, + validated_record.batch_id, + validated_record.checkpoint.endpoint_alias, + ) + except CheckpointConflictError: + raise + except Exception: + checkpoint_load_failure = ResultApplicationError("checkpoint_load") + if checkpoint_load_failure is not None: + raise checkpoint_load_failure from None + if previous_checkpoint is not None: + if type(previous_checkpoint) is not BatchResultCheckpoint: + raise ResultApplicationError("checkpoint_load") from None + if _checkpoint_primitive_type_error(previous_checkpoint) is not None: + raise ResultApplicationError("checkpoint_load") from None + if ( + previous_checkpoint.batch_id != validated_record.checkpoint.batch_id + or previous_checkpoint.endpoint_alias + != validated_record.checkpoint.endpoint_alias + or previous_checkpoint.file_kind != validated_record.checkpoint.file_kind + or previous_checkpoint.file_id != validated_record.checkpoint.file_id + ): + raise ResultApplicationError("checkpoint_load") from None + + if previous_checkpoint == validated_record.checkpoint: + return ResultApplicationOutcome( + record_applied=False, + result_checkpoint=validated_record.checkpoint, + ) + if previous_checkpoint is not None and ( + validated_record.checkpoint.record_count <= previous_checkpoint.record_count + or validated_record.checkpoint.batch_line_count + <= previous_checkpoint.batch_line_count + ): + raise CheckpointConflictError( + consumer_name, + validated_record.batch_id, + "checkpoint_regression", + ) from None + + record_effect_failure: ResultApplicationError | None = None + record_effect_cursor = _ResultApplicationCursor(transaction_cursor) + try: + try: + record_effect_result = record_effect( + record_effect_cursor, + validated_record.record, + ) + finally: + record_effect_cursor._revoke() + if inspect.iscoroutine(record_effect_result): + record_effect_result.close() + elif isinstance(record_effect_result, (asyncio.Future, ConcurrentFuture)): + record_effect_result.cancel() + if record_effect_result is not None: + record_effect_failure = ResultApplicationError("record_effect") + except Exception: + record_effect_failure = ResultApplicationError("record_effect") + if record_effect_failure is not None: + raise record_effect_failure from None + + checkpoint_save_failure: ResultApplicationError | None = None + try: + saved_checkpoint = checkpoint_store.save_in_transaction( + transaction_cursor, + consumer_name, + validated_record.checkpoint, + expected_previous=previous_checkpoint, + ) + if type(saved_checkpoint) is not BatchResultCheckpoint: + checkpoint_save_failure = ResultApplicationError("checkpoint_save") + elif _checkpoint_primitive_type_error(saved_checkpoint) is not None: + checkpoint_save_failure = ResultApplicationError("checkpoint_save") + elif saved_checkpoint != validated_record.checkpoint: + checkpoint_save_failure = ResultApplicationError("checkpoint_save") + except CheckpointConflictError: + raise + except Exception: + checkpoint_save_failure = ResultApplicationError("checkpoint_save") + if checkpoint_save_failure is not None: + raise checkpoint_save_failure from None + + return ResultApplicationOutcome( + record_applied=True, + result_checkpoint=validated_record.checkpoint, + ) def apply_checkpointed_result_in_transaction( @@ -190,6 +344,12 @@ def apply_checkpointed_result_in_transaction( ) -> ResultApplicationOutcome: """Apply one result and advance its checkpoint in the caller's transaction. + ``cursor``, ``item``, and ``apply_record`` are historical released keyword + names retained only at this compatibility boundary. Internally they are + translated immediately to ``transaction_cursor``, ``checkpointed_record``, + and ``record_effect`` so package-owned implementation vocabulary remains + semantically specific. + The item, checkpoint, checkpoint primitive fields, JSON object, loaded predecessor, and save confirmation must use exact package-owned or built-in types. Subclasses are rejected before their behavior-bearing comparison or @@ -226,88 +386,13 @@ def apply_checkpointed_result_in_transaction( after their exception scope has ended, preventing implicit traceback context from retaining provider or database diagnostics. """ - candidate = _validate_item_and_effect(item, apply_record) - - load_failure: ResultApplicationError | None = None - previous: BatchResultCheckpoint | None = None - try: - previous = checkpoint_store.load_in_transaction( - cursor, - consumer_name, - candidate.batch_id, - candidate.checkpoint.endpoint_alias, - ) - except CheckpointConflictError: - raise - except Exception: - load_failure = ResultApplicationError("checkpoint_load") - if load_failure is not None: - raise load_failure from None - if previous is not None: - if type(previous) is not BatchResultCheckpoint: - raise ResultApplicationError("checkpoint_load") from None - if _checkpoint_primitive_type_error(previous) is not None: - raise ResultApplicationError("checkpoint_load") from None - if ( - previous.batch_id != candidate.checkpoint.batch_id - or previous.endpoint_alias != candidate.checkpoint.endpoint_alias - or previous.file_kind != candidate.checkpoint.file_kind - or previous.file_id != candidate.checkpoint.file_id - ): - raise ResultApplicationError("checkpoint_load") from None - - if previous == candidate.checkpoint: - return ResultApplicationOutcome(applied=False, checkpoint=candidate.checkpoint) - if previous is not None and ( - candidate.checkpoint.record_count <= previous.record_count - or candidate.checkpoint.batch_line_count <= previous.batch_line_count - ): - raise CheckpointConflictError( - consumer_name, - candidate.batch_id, - "checkpoint_regression", - ) from None - - effect_failure: ResultApplicationError | None = None - effect_cursor = _ResultApplicationCursor(cursor) - try: - try: - effect_result = apply_record(effect_cursor, candidate.record) - finally: - effect_cursor._revoke() - if inspect.iscoroutine(effect_result): - effect_result.close() - elif isinstance(effect_result, (asyncio.Future, ConcurrentFuture)): - effect_result.cancel() - if effect_result is not None: - effect_failure = ResultApplicationError("record_effect") - except Exception: - effect_failure = ResultApplicationError("record_effect") - if effect_failure is not None: - raise effect_failure from None - - save_failure: ResultApplicationError | None = None - try: - saved_checkpoint = checkpoint_store.save_in_transaction( - cursor, - consumer_name, - candidate.checkpoint, - expected_previous=previous, - ) - if type(saved_checkpoint) is not BatchResultCheckpoint: - save_failure = ResultApplicationError("checkpoint_save") - elif _checkpoint_primitive_type_error(saved_checkpoint) is not None: - save_failure = ResultApplicationError("checkpoint_save") - elif saved_checkpoint != candidate.checkpoint: - save_failure = ResultApplicationError("checkpoint_save") - except CheckpointConflictError: - raise - except Exception: - save_failure = ResultApplicationError("checkpoint_save") - if save_failure is not None: - raise save_failure from None - - return ResultApplicationOutcome(applied=True, checkpoint=candidate.checkpoint) + return _apply_checkpointed_record_in_transaction( + transaction_cursor=cursor, + checkpoint_store=checkpoint_store, + consumer_name=consumer_name, + checkpointed_record=item, + record_effect=apply_record, + ) __all__ = [ From 4f58319c9f993cb48018fc7edad622e93ee92658 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 17:57:48 +0900 Subject: [PATCH 03/57] docs(results): record semantic application boundary --- ...result-application-semantic-identifiers.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 docs/doctoring/result-application-semantic-identifiers.md diff --git a/docs/doctoring/result-application-semantic-identifiers.md b/docs/doctoring/result-application-semantic-identifiers.md new file mode 100644 index 000000000..706deca55 --- /dev/null +++ b/docs/doctoring/result-application-semantic-identifiers.md @@ -0,0 +1,36 @@ +# Result application semantic identifiers + +## Decision + +The Result Application bounded context owns checkpointed provider-record application inside a caller-supplied transaction. Organization-owned implementation names use semantic multiword vocabulary. Historical public Python names remain only at an explicit compatibility boundary when changing them would break released callers. + +## Old → new vocabulary + +- `ResultApplicationError.phase` constructor argument → `application_phase`; the serialized diagnostic key `details["phase"]` remains stable. +- `ResultApplicationOutcome.applied` field → `record_applied`; read-only `applied` remains a compatibility property. +- `ResultApplicationOutcome.checkpoint` field → `result_checkpoint`; read-only `checkpoint` remains a compatibility property. +- private validation `field` / `reason` → `field_name` / `validation_reason`. +- private `item` / `apply_record` → `checkpointed_record` / `record_effect`. +- implementation `cursor` → `transaction_cursor`, `candidate` → `validated_record`, `previous` → `previous_checkpoint`, and phase-specific failure/result locals use semantic multiword names. + +The released function `apply_checkpointed_result_in_transaction(cursor, checkpoint_store, consumer_name, item, apply_record)` keeps its historical keyword signature as an anti-corruption adapter. It immediately translates those names into `_apply_checkpointed_record_in_transaction(transaction_cursor, checkpoint_store, consumer_name, checkpointed_record, record_effect)`. This preserves external source compatibility without allowing generic vocabulary to remain authoritative inside the package. + +## DDD boundary and invariants + +**Bounded Context:** Result Application. **Aggregate interaction:** one checkpointed provider result plus its durable checkpoint advancement. **Domain service:** transactional result application. **Value objects:** `BatchResultCheckpoint` and `CheckpointedBatchResultRecord`. **Invariant:** the local effect and checkpoint save execute in the same caller-owned transaction; exact replay does not reapply the effect; checkpoint regression fails closed; asynchronous/deferred work cannot retain the scoped cursor capability. + +The naming repair changes no provider protocol, PostgreSQL schema, transaction ownership, retry behavior, authorization boundary, or checkpoint ordering semantics. + +## Compatibility and persistence + +There is no database migration, FK/index/constraint change, UPSERT change, partitioning change, lock change, or read/write-topology change. Existing callers may continue to construct `ResultApplicationOutcome(applied=..., checkpoint=...)`, read `.applied` / `.checkpoint`, and call `apply_checkpointed_result_in_transaction` with historical keyword arguments. New package-owned code uses `record_applied`, `result_checkpoint`, `transaction_cursor`, `checkpointed_record`, and `record_effect`. + +## TDD evidence + +The RED-first commit `6e10a87cf8c0f090854672a7453cf20fb2d416e9` adds `tests/test_result_application_naming_contract.py`. Against its exact predecessor production source, the semantic helper signatures, semantic outcome fields, compatibility properties, and semantic core function did not exist. Production repair follows in ordinary non-force history. + +Fresh exact-head repository checks remain authoritative. Predecessor/base check results do not transfer. + +## Rollback + +The code-only repair can be reverted without data migration because neither stored checkpoint rows nor provider/wire payloads change. A rollback restores the prior Python-internal naming while leaving persisted state untouched. From 836b902989a499b203bf3004d09360b334bde8c0 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 17:58:59 +0900 Subject: [PATCH 04/57] docs(product): establish technical gap baseline --- docs/product-technical-gap-baseline.md | 42 ++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 docs/product-technical-gap-baseline.md diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md new file mode 100644 index 000000000..caa7ab6ac --- /dev/null +++ b/docs/product-technical-gap-baseline.md @@ -0,0 +1,42 @@ +# Product–technical gap baseline + +## Product responsibility + +`ContextualWisdomLab/pg-llm-batch` is the independently deployable/embeddable PostgreSQL LLM batch foundation. It owns PostgreSQL configuration and encrypted-secret persistence, database token-count/batch execution support, provider batch HTTP integration, bounded JSONL result streaming, durable lifecycle/checkpoint evidence, and package-level recovery/release evidence. Host products retain their own authentication, authorization, tenant selection, buyer workflow, and domain truth. + +## Bounded-context map + +- **Provider Batch Gateway:** `BatchAPIClient` and provider HTTP/file operations. External provider identifiers and payload keys remain provider contracts and are validated/translated at the adapter boundary. +- **Durable Batch Lifecycle:** tenant-scoped lifecycle persistence with business identity `(tenant_scope, endpoint_alias, remote_batch_id)`, forced PostgreSQL RLS, and standalone compatibility. +- **Result Streaming:** bounded provider JSONL decoding and resumable `BatchResultCheckpoint` evidence. +- **Result Application:** atomically applies a `CheckpointedBatchResultRecord` effect and advances its durable checkpoint in a caller-owned transaction. Semantic internal vocabulary is `transaction_cursor`, `checkpointed_record`, `record_effect`, `record_applied`, and `result_checkpoint`; historical released Python names are compatibility adapters only. +- **Recovery / Release Evidence:** descriptor-bound backup/restore and reproducible release evidence without transferring provider or database content into diagnostics. + +## DDD vocabulary and invariants + +**Aggregates / entities:** durable remote batch lifecycle row, checkpoint consumer state. **Value objects:** `BatchResultCheckpoint`, `CheckpointedBatchResultRecord`, result-application outcome. **Domain services:** provider batch gateway, checkpoint store, result application, backup/restore verification. **Domain events/evidence:** lifecycle observations and content-free recovery/release evidence. + +Key invariants are tenant context before persistence/provider work; forced RLS for ordinary application roles; exact checkpoint monotonicity; same-transaction local effect plus checkpoint advance; bounded provider decoding; fail-closed malformed provider/state evidence; no arbitrary SQL as an authorization substitute; and no generic provider payload field becoming internal domain authority without validation/translation. + +## Naming-contract status + +Current naming repair owner: branch `fix/result-application-semantic-identifiers`, based on protected `main@b84f0c94154043a3473939c01bb6471de5a129ae`. + +The Result Application slice translates ambiguous package-owned names into semantic multiword vocabulary while keeping historical released names only at a documented compatibility boundary. RED-first evidence is commit `6e10a87cf8c0f090854672a7453cf20fb2d416e9`; production repair begins at `6e12edbe7e320ae4d3396837d4b3517808f2c2bc`. Fresh exact-head CI after all documentation commits is required before merge; predecessor evidence does not transfer. + +No database object changes occur in this slice, so there is no migration, FK/index/constraint, UPSERT, 3NF, partition, locking, or read/write-topology change. Persisted checkpoint data and provider wire contracts remain unchanged. + +## Current product / technical gaps + +1. **Naming conformance:** continue repository-wide review of package-owned result-streaming, release-evidence, persistence, workflow, tests, and documentation identifiers. Prioritize public/persisted/shared contracts and preserve vendor/protocol names at adapters. +2. **Verification:** every source or contract repair requires exact-head tests, 100% required statement/branch/public-doc coverage, security checks, and current independent review under ordinary protection. +3. **Release evidence:** source versions and green development checks are not immutable release evidence; product claims must remain tied to actual release artifacts and reproducibility/provenance evidence. +4. **Consumer integration:** downstream hosts such as `contextual-orchestrator` and `naruon` consume released package contracts and provide authenticated tenant context; they must not copy package source or read package persistence as a cross-service shortcut. + +## Security / operability baseline + +The current architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries for idempotent GET operations only, redacted diagnostics, deterministic checkpoint conflict behavior, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated regressions and doctoring rather than being hidden inside naming refactors. + +## Evidence status + +This baseline records repository truth visible on the current naming branch. It does not claim fresh exact-head workflow success, independent approval, release publication, buyer deployment, or downstream consumer validation until those artifacts exist on the unchanged final head. From d2c88e095fe9ee6ffc123ad766bb9a1c0ff3a040 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 17:59:30 +0900 Subject: [PATCH 05/57] docs(architecture): define result application ACL --- ARCHITECTURE.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 306381841..21fd08825 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -70,6 +70,22 @@ Post-restore metadata mismatch is fail-closed and must be treated as unsafe because the SQL transaction may already have committed. This seam does not complete isolated schema/RLS/PITR acceptance. +## Result application boundary + +Checkpointed result application is a package-owned domain service. Internally, +its ubiquitous language is `transaction_cursor`, `checkpointed_record`, +`record_effect`, `record_applied`, and `result_checkpoint`. The released +`apply_checkpointed_result_in_transaction(cursor, checkpoint_store, +consumer_name, item, apply_record)` signature and the historical outcome reads +`.applied` / `.checkpoint` remain compatibility adapters only; they translate at +the package boundary rather than defining internal domain vocabulary. + +The service preserves the same transaction and replay invariants: the local +record effect and checkpoint save occur under the caller-owned transaction, +exact replay skips the effect, checkpoint regression fails closed, and the +scoped cursor is revoked when synchronous effect execution ends. This naming +boundary changes no provider protocol or database schema. + ## Modular interoperability CWL hosts such as `contextual-orchestrator` and `naruon` supply tenant context From f55c3d6fdf49ec460ea3354626f97912ef30eb16 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:00:10 +0900 Subject: [PATCH 06/57] docs(changelog): record result naming compatibility --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 48e37288f..1c95858a3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -135,6 +135,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed +- Replaced generic package-owned Result Application implementation names with + `application_phase`, `record_applied`, `result_checkpoint`, + `transaction_cursor`, `checkpointed_record`, and `record_effect`. Historical + `apply_checkpointed_result_in_transaction(cursor, ..., item, apply_record)`, + `ResultApplicationOutcome(applied=..., checkpoint=...)`, and `.applied` / + `.checkpoint` reads remain explicit source-compatibility adapters; provider + wire contracts and PostgreSQL persistence are unchanged. - Bound repository CI checkouts to the exact pull-request source head and verify the checked-out commit before tests, coverage, packaging, or container gates. - Migrated package licensing to PEP 639 with an SPDX `Apache-2.0` expression, From cf4afec24e917a679dcdd28f330f18322a8739aa Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:03:55 +0900 Subject: [PATCH 07/57] test(results): cover semantic compatibility branches --- ...test_result_application_naming_contract.py | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) diff --git a/tests/test_result_application_naming_contract.py b/tests/test_result_application_naming_contract.py index 18520679d..bebd881c7 100644 --- a/tests/test_result_application_naming_contract.py +++ b/tests/test_result_application_naming_contract.py @@ -3,7 +3,25 @@ from dataclasses import fields from inspect import signature +import pytest + from pg_llm_batch import result_application as result_application +from pg_llm_batch.result_streaming import BatchResultCheckpoint + + +def _checkpoint() -> BatchResultCheckpoint: + """Build one valid checkpoint for semantic/legacy outcome compatibility tests.""" + return BatchResultCheckpoint( + schema_version=1, + batch_id="batch-123", + endpoint_alias="openrouter", + file_kind="result", + file_id="file-123", + file_line_number=1, + batch_line_count=1, + record_count=1, + prefix_sha256="a" * 64, + ) def test_result_application_internal_signatures_use_semantic_names() -> None: @@ -41,6 +59,65 @@ def test_result_application_outcome_uses_semantic_fields_with_legacy_accessors() assert isinstance(result_application.ResultApplicationOutcome.checkpoint, property) +def test_semantic_outcome_construction_exposes_legacy_reads() -> None: + """New semantic construction remains readable through released legacy properties.""" + result_checkpoint = _checkpoint() + application_outcome = result_application.ResultApplicationOutcome( + record_applied=True, + result_checkpoint=result_checkpoint, + ) + + assert application_outcome.record_applied is True + assert application_outcome.result_checkpoint is result_checkpoint + assert application_outcome.applied is True + assert application_outcome.checkpoint is result_checkpoint + + +def test_legacy_outcome_construction_populates_semantic_fields() -> None: + """Released constructor keywords translate immediately into semantic fields.""" + result_checkpoint = _checkpoint() + application_outcome = result_application.ResultApplicationOutcome( + applied=False, + checkpoint=result_checkpoint, + ) + + assert application_outcome.record_applied is False + assert application_outcome.result_checkpoint is result_checkpoint + + +def test_outcome_rejects_duplicate_applied_vocabulary() -> None: + """Callers cannot supply both semantic and legacy applied flags ambiguously.""" + with pytest.raises(TypeError, match="record_applied or legacy applied"): + result_application.ResultApplicationOutcome( + record_applied=True, + applied=False, + result_checkpoint=_checkpoint(), + ) + + +def test_outcome_rejects_duplicate_checkpoint_vocabulary() -> None: + """Callers cannot supply both semantic and legacy checkpoint values ambiguously.""" + result_checkpoint = _checkpoint() + with pytest.raises(TypeError, match="result_checkpoint or legacy checkpoint"): + result_application.ResultApplicationOutcome( + record_applied=True, + result_checkpoint=result_checkpoint, + checkpoint=result_checkpoint, + ) + + +def test_outcome_requires_applied_value() -> None: + """Either semantic or legacy applied vocabulary is required explicitly.""" + with pytest.raises(TypeError, match="record_applied is required"): + result_application.ResultApplicationOutcome(result_checkpoint=_checkpoint()) + + +def test_outcome_requires_checkpoint_value() -> None: + """Either semantic or legacy checkpoint vocabulary is required explicitly.""" + with pytest.raises(TypeError, match="result_checkpoint is required"): + result_application.ResultApplicationOutcome(record_applied=True) + + def test_legacy_public_function_remains_an_explicit_compatibility_adapter() -> None: """Existing keyword callers retain the released parameter contract at the ACL boundary.""" assert tuple( From cefc0c3723a4f093fb8181bae0c596a1796f7668 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:05:20 +0900 Subject: [PATCH 08/57] test(results): preserve released outcome dataclass shape --- ...test_result_application_naming_contract.py | 83 ++++++------------- 1 file changed, 24 insertions(+), 59 deletions(-) diff --git a/tests/test_result_application_naming_contract.py b/tests/test_result_application_naming_contract.py index bebd881c7..7c4678b1c 100644 --- a/tests/test_result_application_naming_contract.py +++ b/tests/test_result_application_naming_contract.py @@ -1,10 +1,8 @@ """Naming-contract regressions for checkpointed result application.""" -from dataclasses import fields +from dataclasses import asdict, fields from inspect import signature -import pytest - from pg_llm_batch import result_application as result_application from pg_llm_batch.result_streaming import BatchResultCheckpoint @@ -49,73 +47,40 @@ def test_result_application_internal_signatures_use_semantic_names() -> None: ) -def test_result_application_outcome_uses_semantic_fields_with_legacy_accessors() -> None: - """The domain result owns semantic fields while legacy attribute reads stay compatible.""" - assert {field.name for field in fields(result_application.ResultApplicationOutcome)} == { - "record_applied", - "result_checkpoint", - } - assert isinstance(result_application.ResultApplicationOutcome.applied, property) - assert isinstance(result_application.ResultApplicationOutcome.checkpoint, property) - - -def test_semantic_outcome_construction_exposes_legacy_reads() -> None: - """New semantic construction remains readable through released legacy properties.""" +def test_public_outcome_preserves_released_dataclass_contract() -> None: + """The released dataclass shape remains stable at the compatibility boundary.""" result_checkpoint = _checkpoint() application_outcome = result_application.ResultApplicationOutcome( - record_applied=True, - result_checkpoint=result_checkpoint, + applied=True, + checkpoint=result_checkpoint, ) + assert {field.name for field in fields(result_application.ResultApplicationOutcome)} == { + "applied", + "checkpoint", + } + assert asdict(application_outcome) == { + "applied": True, + "checkpoint": asdict(result_checkpoint), + } assert application_outcome.record_applied is True assert application_outcome.result_checkpoint is result_checkpoint - assert application_outcome.applied is True - assert application_outcome.checkpoint is result_checkpoint -def test_legacy_outcome_construction_populates_semantic_fields() -> None: - """Released constructor keywords translate immediately into semantic fields.""" +def test_internal_outcome_owns_semantic_fields() -> None: + """Package-owned execution state uses semantic names behind the public adapter.""" result_checkpoint = _checkpoint() - application_outcome = result_application.ResultApplicationOutcome( - applied=False, - checkpoint=result_checkpoint, + semantic_outcome = result_application._SemanticResultApplicationOutcome( + record_applied=False, + result_checkpoint=result_checkpoint, ) - assert application_outcome.record_applied is False - assert application_outcome.result_checkpoint is result_checkpoint - - -def test_outcome_rejects_duplicate_applied_vocabulary() -> None: - """Callers cannot supply both semantic and legacy applied flags ambiguously.""" - with pytest.raises(TypeError, match="record_applied or legacy applied"): - result_application.ResultApplicationOutcome( - record_applied=True, - applied=False, - result_checkpoint=_checkpoint(), - ) - - -def test_outcome_rejects_duplicate_checkpoint_vocabulary() -> None: - """Callers cannot supply both semantic and legacy checkpoint values ambiguously.""" - result_checkpoint = _checkpoint() - with pytest.raises(TypeError, match="result_checkpoint or legacy checkpoint"): - result_application.ResultApplicationOutcome( - record_applied=True, - result_checkpoint=result_checkpoint, - checkpoint=result_checkpoint, - ) - - -def test_outcome_requires_applied_value() -> None: - """Either semantic or legacy applied vocabulary is required explicitly.""" - with pytest.raises(TypeError, match="record_applied is required"): - result_application.ResultApplicationOutcome(result_checkpoint=_checkpoint()) - - -def test_outcome_requires_checkpoint_value() -> None: - """Either semantic or legacy checkpoint vocabulary is required explicitly.""" - with pytest.raises(TypeError, match="result_checkpoint is required"): - result_application.ResultApplicationOutcome(record_applied=True) + assert { + field.name + for field in fields(result_application._SemanticResultApplicationOutcome) + } == {"record_applied", "result_checkpoint"} + assert semantic_outcome.record_applied is False + assert semantic_outcome.result_checkpoint is result_checkpoint def test_legacy_public_function_remains_an_explicit_compatibility_adapter() -> None: From b58c11f0f263b3d1d4141b37acaed8430101c8a9 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:06:23 +0900 Subject: [PATCH 09/57] fix(results): preserve public outcome compatibility --- pg_llm_batch/result_application.py | 105 +++++++++++++---------------- 1 file changed, 48 insertions(+), 57 deletions(-) diff --git a/pg_llm_batch/result_application.py b/pg_llm_batch/result_application.py index 8fcdef6b7..3c981c580 100644 --- a/pg_llm_batch/result_application.py +++ b/pg_llm_batch/result_application.py @@ -38,54 +38,37 @@ def __init__(self, application_phase: str) -> None: ) -@dataclass(frozen=True, init=False) +@dataclass(frozen=True) class ResultApplicationOutcome: - """Describe whether one local record effect was newly applied. + """Preserve the released result-application outcome contract. - ``record_applied`` and ``result_checkpoint`` are the package-owned semantic - fields. The historical ``applied`` and ``checkpoint`` constructor keywords - and read-only properties remain as a compatibility boundary for released - callers. + ``applied`` and ``checkpoint`` are historical public dataclass fields. They + remain at this compatibility boundary because changing dataclass field names + would alter construction, introspection, and ``dataclasses.asdict`` output. + New package-owned implementation code uses the semantic + :class:`_SemanticResultApplicationOutcome` instead. """ - record_applied: bool - result_checkpoint: BatchResultCheckpoint - - def __init__( - self, - record_applied: bool | None = None, - result_checkpoint: BatchResultCheckpoint | None = None, - *, - applied: bool | None = None, - checkpoint: BatchResultCheckpoint | None = None, - ) -> None: - """Normalize semantic or legacy outcome arguments without ambiguity.""" - if record_applied is not None and applied is not None: - raise TypeError("use record_applied or legacy applied, not both") - if result_checkpoint is not None and checkpoint is not None: - raise TypeError("use result_checkpoint or legacy checkpoint, not both") - normalized_record_applied = ( - record_applied if record_applied is not None else applied - ) - normalized_result_checkpoint = ( - result_checkpoint if result_checkpoint is not None else checkpoint - ) - if normalized_record_applied is None: - raise TypeError("record_applied is required") - if normalized_result_checkpoint is None: - raise TypeError("result_checkpoint is required") - object.__setattr__(self, "record_applied", normalized_record_applied) - object.__setattr__(self, "result_checkpoint", normalized_result_checkpoint) + applied: bool + checkpoint: BatchResultCheckpoint @property - def applied(self) -> bool: - """Return the legacy applied flag for source compatibility.""" - return self.record_applied + def record_applied(self) -> bool: + """Expose the semantic applied-state name to new callers.""" + return self.applied @property - def checkpoint(self) -> BatchResultCheckpoint: - """Return the legacy checkpoint attribute for source compatibility.""" - return self.result_checkpoint + def result_checkpoint(self) -> BatchResultCheckpoint: + """Expose the semantic checkpoint name to new callers.""" + return self.checkpoint + + +@dataclass(frozen=True) +class _SemanticResultApplicationOutcome: + """Represent package-owned result-application state with semantic names.""" + + record_applied: bool + result_checkpoint: BatchResultCheckpoint class _ResultApplicationCursor: @@ -99,49 +82,53 @@ class _ResultApplicationCursor: is touched. """ - __slots__ = ("__active", "__cursor", "__owner_thread_id") + __slots__ = ( + "__capability_active", + "__transaction_cursor", + "__owner_thread_id", + ) - def __init__(self, cursor: Any) -> None: + def __init__(self, transaction_cursor: Any) -> None: """Bind one raw cursor to the constructing thread for one callback.""" - self.__cursor = cursor + self.__transaction_cursor = transaction_cursor self.__owner_thread_id = get_ident() - self.__active = True + self.__capability_active = True - def _revoke(self) -> None: + def _revoke_cursor_capability(self) -> None: """Remove package-supplied cursor authority after callback completion.""" - self.__active = False + self.__capability_active = False def _assert_usable(self) -> None: """Reject expired or cross-thread use with bounded package evidence.""" - if not self.__active or get_ident() != self.__owner_thread_id: + if not self.__capability_active or get_ident() != self.__owner_thread_id: raise ResultApplicationError("record_effect") from None def execute(self, *args: Any, **kwargs: Any) -> _ResultApplicationCursor: """Execute one statement synchronously without returning the raw cursor.""" self._assert_usable() - self.__cursor.execute(*args, **kwargs) + self.__transaction_cursor.execute(*args, **kwargs) return self def executemany(self, *args: Any, **kwargs: Any) -> _ResultApplicationCursor: """Execute one parameter sequence without returning the raw cursor.""" self._assert_usable() - self.__cursor.executemany(*args, **kwargs) + self.__transaction_cursor.executemany(*args, **kwargs) return self def fetchone(self, *args: Any, **kwargs: Any) -> Any: """Fetch one result while this callback owns the scoped capability.""" self._assert_usable() - return self.__cursor.fetchone(*args, **kwargs) + return self.__transaction_cursor.fetchone(*args, **kwargs) def fetchmany(self, *args: Any, **kwargs: Any) -> Any: """Fetch a bounded result page while the scoped capability is active.""" self._assert_usable() - return self.__cursor.fetchmany(*args, **kwargs) + return self.__transaction_cursor.fetchmany(*args, **kwargs) def fetchall(self, *args: Any, **kwargs: Any) -> Any: """Fetch remaining results while the scoped capability is active.""" self._assert_usable() - return self.__cursor.fetchall(*args, **kwargs) + return self.__transaction_cursor.fetchall(*args, **kwargs) def _redacted_validation_error( @@ -238,7 +225,7 @@ def _apply_checkpointed_record_in_transaction( consumer_name: str, checkpointed_record: CheckpointedBatchResultRecord, record_effect: Callable[[Any, Mapping[str, Any]], None], -) -> ResultApplicationOutcome: +) -> _SemanticResultApplicationOutcome: """Apply one semantic checkpointed record within the caller transaction.""" validated_record = _validate_item_and_effect(checkpointed_record, record_effect) @@ -272,7 +259,7 @@ def _apply_checkpointed_record_in_transaction( raise ResultApplicationError("checkpoint_load") from None if previous_checkpoint == validated_record.checkpoint: - return ResultApplicationOutcome( + return _SemanticResultApplicationOutcome( record_applied=False, result_checkpoint=validated_record.checkpoint, ) @@ -296,7 +283,7 @@ def _apply_checkpointed_record_in_transaction( validated_record.record, ) finally: - record_effect_cursor._revoke() + record_effect_cursor._revoke_cursor_capability() if inspect.iscoroutine(record_effect_result): record_effect_result.close() elif isinstance(record_effect_result, (asyncio.Future, ConcurrentFuture)): @@ -329,7 +316,7 @@ def _apply_checkpointed_record_in_transaction( if checkpoint_save_failure is not None: raise checkpoint_save_failure from None - return ResultApplicationOutcome( + return _SemanticResultApplicationOutcome( record_applied=True, result_checkpoint=validated_record.checkpoint, ) @@ -386,13 +373,17 @@ def apply_checkpointed_result_in_transaction( after their exception scope has ended, preventing implicit traceback context from retaining provider or database diagnostics. """ - return _apply_checkpointed_record_in_transaction( + semantic_outcome = _apply_checkpointed_record_in_transaction( transaction_cursor=cursor, checkpoint_store=checkpoint_store, consumer_name=consumer_name, checkpointed_record=item, record_effect=apply_record, ) + return ResultApplicationOutcome( + applied=semantic_outcome.record_applied, + checkpoint=semantic_outcome.result_checkpoint, + ) __all__ = [ From e054066e542e0bee3827177b8d03fb5d6fa67455 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:06:55 +0900 Subject: [PATCH 10/57] docs(results): preserve dataclass compatibility boundary --- .../result-application-semantic-identifiers.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/doctoring/result-application-semantic-identifiers.md b/docs/doctoring/result-application-semantic-identifiers.md index 706deca55..004f7da02 100644 --- a/docs/doctoring/result-application-semantic-identifiers.md +++ b/docs/doctoring/result-application-semantic-identifiers.md @@ -2,18 +2,19 @@ ## Decision -The Result Application bounded context owns checkpointed provider-record application inside a caller-supplied transaction. Organization-owned implementation names use semantic multiword vocabulary. Historical public Python names remain only at an explicit compatibility boundary when changing them would break released callers. +The Result Application bounded context owns checkpointed provider-record application inside a caller-supplied transaction. Organization-owned implementation names use semantic multiword vocabulary. Historical public Python names remain only at explicit compatibility boundaries when changing them would break released callers, including Python dataclass field/introspection shape. ## Old → new vocabulary - `ResultApplicationError.phase` constructor argument → `application_phase`; the serialized diagnostic key `details["phase"]` remains stable. -- `ResultApplicationOutcome.applied` field → `record_applied`; read-only `applied` remains a compatibility property. -- `ResultApplicationOutcome.checkpoint` field → `result_checkpoint`; read-only `checkpoint` remains a compatibility property. +- Internal result state now uses `_SemanticResultApplicationOutcome.record_applied` and `.result_checkpoint`. +- Public `ResultApplicationOutcome.applied` and `.checkpoint` remain the released dataclass fields so constructor keywords, `dataclasses.fields`, and `dataclasses.asdict` retain their historical shape; new semantic read properties `.record_applied` and `.result_checkpoint` are additive. - private validation `field` / `reason` → `field_name` / `validation_reason`. - private `item` / `apply_record` → `checkpointed_record` / `record_effect`. - implementation `cursor` → `transaction_cursor`, `candidate` → `validated_record`, `previous` → `previous_checkpoint`, and phase-specific failure/result locals use semantic multiword names. +- `_ResultApplicationCursor` now owns `transaction_cursor`, `capability_active`, and `revoke_cursor_capability` vocabulary internally while DB-API method names such as `execute`, `executemany`, and `fetchone` remain adapter protocol names. -The released function `apply_checkpointed_result_in_transaction(cursor, checkpoint_store, consumer_name, item, apply_record)` keeps its historical keyword signature as an anti-corruption adapter. It immediately translates those names into `_apply_checkpointed_record_in_transaction(transaction_cursor, checkpoint_store, consumer_name, checkpointed_record, record_effect)`. This preserves external source compatibility without allowing generic vocabulary to remain authoritative inside the package. +The released function `apply_checkpointed_result_in_transaction(cursor, checkpoint_store, consumer_name, item, apply_record)` keeps its historical keyword signature as an anti-corruption adapter. It immediately translates those names into `_apply_checkpointed_record_in_transaction(transaction_cursor, checkpoint_store, consumer_name, checkpointed_record, record_effect)` and converts the semantic internal outcome back to the stable public dataclass. This preserves external source and dataclass-serialization compatibility without allowing generic vocabulary to remain authoritative inside the package. ## DDD boundary and invariants @@ -23,11 +24,11 @@ The naming repair changes no provider protocol, PostgreSQL schema, transaction o ## Compatibility and persistence -There is no database migration, FK/index/constraint change, UPSERT change, partitioning change, lock change, or read/write-topology change. Existing callers may continue to construct `ResultApplicationOutcome(applied=..., checkpoint=...)`, read `.applied` / `.checkpoint`, and call `apply_checkpointed_result_in_transaction` with historical keyword arguments. New package-owned code uses `record_applied`, `result_checkpoint`, `transaction_cursor`, `checkpointed_record`, and `record_effect`. +There is no database migration, FK/index/constraint change, UPSERT change, partitioning change, lock change, or read/write-topology change. Existing callers may continue to construct `ResultApplicationOutcome(applied=..., checkpoint=...)`, inspect/serialize those dataclass fields, read `.applied` / `.checkpoint`, and call `apply_checkpointed_result_in_transaction` with historical keyword arguments. Additive semantic public reads `.record_applied` / `.result_checkpoint` and the private semantic core provide the new ubiquitous language without silently changing released shape. ## TDD evidence -The RED-first commit `6e10a87cf8c0f090854672a7453cf20fb2d416e9` adds `tests/test_result_application_naming_contract.py`. Against its exact predecessor production source, the semantic helper signatures, semantic outcome fields, compatibility properties, and semantic core function did not exist. Production repair follows in ordinary non-force history. +The RED-first commit `6e10a87cf8c0f090854672a7453cf20fb2d416e9` established semantic internal signatures. A later compatibility review identified that making the public dataclass fields semantic would change `dataclasses.fields`/`dataclasses.asdict`; RED commit `cefc0c3723a4f093fb8181bae0c596a1796f7668` therefore pinned the released dataclass shape plus a private semantic outcome model before production repair in `b58c11f0f263b3d1d4141b37acaed8430101c8a9`. Fresh exact-head repository checks remain authoritative. Predecessor/base check results do not transfer. From 341d7c1945f5bb921655c9a6d633ff2756f68147 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:07:21 +0900 Subject: [PATCH 11/57] docs(architecture): preserve released outcome shape --- ARCHITECTURE.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 21fd08825..27a51b831 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -76,9 +76,13 @@ Checkpointed result application is a package-owned domain service. Internally, its ubiquitous language is `transaction_cursor`, `checkpointed_record`, `record_effect`, `record_applied`, and `result_checkpoint`. The released `apply_checkpointed_result_in_transaction(cursor, checkpoint_store, -consumer_name, item, apply_record)` signature and the historical outcome reads -`.applied` / `.checkpoint` remain compatibility adapters only; they translate at -the package boundary rather than defining internal domain vocabulary. +consumer_name, item, apply_record)` keyword signature and the public +`ResultApplicationOutcome(applied, checkpoint)` dataclass field/introspection +shape remain compatibility adapters because renaming them would be a released +source/serialization break. The adapter immediately translates to/from a +private semantic outcome model. Additive `.record_applied` and +`.result_checkpoint` properties expose the semantic vocabulary without changing +historical `dataclasses.fields` or `dataclasses.asdict` output. The service preserves the same transaction and replay invariants: the local record effect and checkpoint save occur under the caller-owned transaction, From 28d2fe47fa9713675aea74a56b88be83411b1ece Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:08:03 +0900 Subject: [PATCH 12/57] docs(changelog): clarify outcome compatibility --- CHANGELOG.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c95858a3..1b203641c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -137,11 +137,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Replaced generic package-owned Result Application implementation names with `application_phase`, `record_applied`, `result_checkpoint`, - `transaction_cursor`, `checkpointed_record`, and `record_effect`. Historical - `apply_checkpointed_result_in_transaction(cursor, ..., item, apply_record)`, - `ResultApplicationOutcome(applied=..., checkpoint=...)`, and `.applied` / - `.checkpoint` reads remain explicit source-compatibility adapters; provider - wire contracts and PostgreSQL persistence are unchanged. + `transaction_cursor`, `checkpointed_record`, and `record_effect`. The released + `apply_checkpointed_result_in_transaction(cursor, ..., item, apply_record)` + keyword signature and public `ResultApplicationOutcome(applied, checkpoint)` + dataclass field/introspection/`asdict` shape remain unchanged at an explicit + compatibility boundary; additive `.record_applied` and `.result_checkpoint` + reads expose semantic vocabulary while provider wire contracts and PostgreSQL + persistence remain unchanged. - Bound repository CI checkouts to the exact pull-request source head and verify the checked-out commit before tests, coverage, packaging, or container gates. - Migrated package licensing to PEP 639 with an SPDX `Apache-2.0` expression, From 3a830e1404c35deb9682e8b0b1b6a555b58f6dd1 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:34:14 +0900 Subject: [PATCH 13/57] test(results): preserve public error keyword compatibility --- tests/test_result_application_naming_contract.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/tests/test_result_application_naming_contract.py b/tests/test_result_application_naming_contract.py index 7c4678b1c..2c200bf56 100644 --- a/tests/test_result_application_naming_contract.py +++ b/tests/test_result_application_naming_contract.py @@ -23,11 +23,13 @@ def _checkpoint() -> BatchResultCheckpoint: def test_result_application_internal_signatures_use_semantic_names() -> None: - """Owned helpers describe checkpointed-result semantics instead of generic values.""" + """Owned private helpers use semantic names without breaking public keywords.""" assert tuple(signature(result_application.ResultApplicationError.__init__).parameters) == ( "self", - "application_phase", + "phase", ) + public_error = result_application.ResultApplicationError(phase="checkpoint_load") + assert public_error.details == {"phase": "checkpoint_load"} assert tuple(signature(result_application._redacted_validation_error).parameters) == ( "field_name", "validation_reason", @@ -48,7 +50,7 @@ def test_result_application_internal_signatures_use_semantic_names() -> None: def test_public_outcome_preserves_released_dataclass_contract() -> None: - """The released dataclass shape remains stable at the compatibility boundary.""" + """The public dataclass shape remains stable at the compatibility boundary.""" result_checkpoint = _checkpoint() application_outcome = result_application.ResultApplicationOutcome( applied=True, @@ -84,7 +86,7 @@ def test_internal_outcome_owns_semantic_fields() -> None: def test_legacy_public_function_remains_an_explicit_compatibility_adapter() -> None: - """Existing keyword callers retain the released parameter contract at the ACL boundary.""" + """Existing keyword callers retain the public parameter contract at the ACL boundary.""" assert tuple( signature(result_application.apply_checkpointed_result_in_transaction).parameters ) == ( From f4de3a25011c185d5ac6ed548dab7d376e72c3ec Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 18:35:06 +0900 Subject: [PATCH 14/57] fix(results): preserve public error keyword compatibility --- pg_llm_batch/result_application.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/pg_llm_batch/result_application.py b/pg_llm_batch/result_application.py index 3c981c580..f9ae99889 100644 --- a/pg_llm_batch/result_application.py +++ b/pg_llm_batch/result_application.py @@ -29,12 +29,12 @@ class ResultApplicationError(PgLlmBatchError): """Report one bounded failure while applying a checkpointed result.""" - def __init__(self, application_phase: str) -> None: - """Create fixed diagnostic evidence for one application phase.""" + def __init__(self, phase: str) -> None: + """Create fixed diagnostic evidence for one public application phase.""" super().__init__( message="Checkpointed result application failed", error_code="RESULT_APPLICATION_ERROR", - details={"phase": application_phase}, + details={"phase": phase}, ) From 9b0cc39d35fcb2d931b7dba2155805964a493e53 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 7 Sep 2026 18:48:33 +0900 Subject: [PATCH 15/57] docs(gaps): converge current Result Application evidence --- docs/product-technical-gap-baseline.md | 41 ++++++++++++++++---------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index caa7ab6ac..adf1fa4fc 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -2,41 +2,50 @@ ## Product responsibility -`ContextualWisdomLab/pg-llm-batch` is the independently deployable/embeddable PostgreSQL LLM batch foundation. It owns PostgreSQL configuration and encrypted-secret persistence, database token-count/batch execution support, provider batch HTTP integration, bounded JSONL result streaming, durable lifecycle/checkpoint evidence, and package-level recovery/release evidence. Host products retain their own authentication, authorization, tenant selection, buyer workflow, and domain truth. +`ContextualWisdomLab/pg-llm-batch` is the canonical PostgreSQL foundation for durable/asynchronous LLM batch execution, token/size accounting, lifecycle persistence, tenant/RLS enforcement, result streaming/application, and the provider-neutral `BatchInferencePort` boundary. Host products retain authentication journeys, tenant selection, buyer workflow, and domain truth; consumers use released contracts rather than copied source, cross-service SQL, or mutable sibling heads. ## Bounded-context map -- **Provider Batch Gateway:** `BatchAPIClient` and provider HTTP/file operations. External provider identifiers and payload keys remain provider contracts and are validated/translated at the adapter boundary. -- **Durable Batch Lifecycle:** tenant-scoped lifecycle persistence with business identity `(tenant_scope, endpoint_alias, remote_batch_id)`, forced PostgreSQL RLS, and standalone compatibility. +- **Provider Batch Gateway:** provider-neutral batch inference and provider HTTP/file adapters. External provider identifiers remain adapter contracts rather than internal domain authority. +- **Durable Batch Lifecycle:** tenant-scoped lifecycle persistence with business identity `(tenant_scope, endpoint_alias, remote_batch_id)`, forced PostgreSQL RLS, and durable transition evidence. - **Result Streaming:** bounded provider JSONL decoding and resumable `BatchResultCheckpoint` evidence. -- **Result Application:** atomically applies a `CheckpointedBatchResultRecord` effect and advances its durable checkpoint in a caller-owned transaction. Semantic internal vocabulary is `transaction_cursor`, `checkpointed_record`, `record_effect`, `record_applied`, and `result_checkpoint`; historical released Python names are compatibility adapters only. +- **Result Application:** applies one `CheckpointedBatchResultRecord` effect and advances its checkpoint in the same caller-owned transaction. Package-owned vocabulary is `transaction_cursor`, `checkpointed_record`, `record_effect`, `record_applied`, and `result_checkpoint`; historical public Python names remain compatibility adapters. - **Recovery / Release Evidence:** descriptor-bound backup/restore and reproducible release evidence without transferring provider or database content into diagnostics. ## DDD vocabulary and invariants -**Aggregates / entities:** durable remote batch lifecycle row, checkpoint consumer state. **Value objects:** `BatchResultCheckpoint`, `CheckpointedBatchResultRecord`, result-application outcome. **Domain services:** provider batch gateway, checkpoint store, result application, backup/restore verification. **Domain events/evidence:** lifecycle observations and content-free recovery/release evidence. +**Aggregates / entities:** durable remote batch lifecycle row and checkpoint consumer state. **Value objects:** `BatchResultCheckpoint`, `CheckpointedBatchResultRecord`, result-application outcome, tenant/provider identities, and bounded accounting values. **Domain services:** provider batch gateway, checkpoint store, result application, lifecycle transition service, and backup/restore verification. **Domain evidence:** lifecycle observations, checkpoint advancement, and content-free recovery/release evidence. -Key invariants are tenant context before persistence/provider work; forced RLS for ordinary application roles; exact checkpoint monotonicity; same-transaction local effect plus checkpoint advance; bounded provider decoding; fail-closed malformed provider/state evidence; no arbitrary SQL as an authorization substitute; and no generic provider payload field becoming internal domain authority without validation/translation. +Current invariants include tenant context before persistence/provider work; forced RLS for ordinary application roles; exact checkpoint monotonicity; same-transaction local effect plus checkpoint advance; bounded exact-JSON snapshots; fail-closed malformed or behavior-bearing authority; redacted diagnostics; and no arbitrary SQL or provider payload field becoming authorization/domain authority without validation and translation. -## Naming-contract status +## Result Application source authority -Current naming repair owner: branch `fix/result-application-semantic-identifiers`, based on protected `main@b84f0c94154043a3473939c01bb6471de5a129ae`. +The canonical source/test parent is PR #277 on `fix/result-application-snapshot-b84f0c9`, exact `4937426e3bab44cb62d641de6205bd6da2d934fc`, based on dependency-root #233 exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. -The Result Application slice translates ambiguous package-owned names into semantic multiword vocabulary while keeping historical released names only at a documented compatibility boundary. RED-first evidence is commit `6e10a87cf8c0f090854672a7453cf20fb2d416e9`; production repair begins at `6e12edbe7e320ae4d3396837d4b3517808f2c2bc`. Fresh exact-head CI after all documentation commits is required before merge; predecessor evidence does not transfer. +Hosted predecessor `ea1caf38caf0318e3f2613ab1d208e0236f93194` exposed a real verification defect after its non-force #233 merge: Release Acceptance succeeded and Python 3.10/3.12/3.14 plus PostgreSQL/container jobs passed, but CI `34105321157` failed the repository 100% coverage gate because four integer-budget defensive branches in `result_application.py` were uncovered. Test-only repair `4937426e3bab44cb62d641de6205bd6da2d934fc` covers exhausted byte budget, zero magnitude, negative-sign accounting, and conservative pre-materialization rejection without changing production behavior or public API. -No database object changes occur in this slice, so there is no migration, FK/index/constraint, UPSERT, 3NF, partition, locking, or read/write-topology change. Persisted checkpoint data and provider wire contracts remain unchanged. +Exact repaired parent evidence is GREEN: Release Acceptance `34107680525` and CI `34107680536` succeeded; coverage/package job `101696358568` recorded `1371 passed / 5 deselected`, production statements `3777/3777`, branches `1066/1066`, `result_application.py` `282/282` statements and `122/122` branches, 100% public docstrings, Ruff/lock/package success, and the Python 3.10/3.12/3.14 plus PostgreSQL/container jobs all succeeded. + +## Documentation authority and convergence + +PR #324 on `fix/result-application-semantic-identifiers` is the documentation-only child of #277. It owns the Result Application naming explanation in `ARCHITECTURE.md`, `CHANGELOG.md`, `docs/doctoring/result-application-semantic-identifiers.md`, and this baseline; it must not regain production/test authority already owned by #277. + +The previous documentation head inherited #277's uncovered-branch failure. It has been non-force restacked onto repaired #277 rather than rebased destructively or allowed to carry stale GREEN. Every documentation edit, including this baseline repair, requires new exact-head verification. + +The active lifecycle/outbox security work in sibling PR #319 is not part of this branch ancestry. Therefore this document does not copy #319 source authority or claim its hosted evidence as current-branch truth. Final documentation convergence must occur only after the source topology legitimately integrates the relevant lifecycle/outbox delta; at that point the canonical baseline must preserve both Result Application and lifecycle/outbox evidence rather than selecting one lineage and dropping the other. ## Current product / technical gaps -1. **Naming conformance:** continue repository-wide review of package-owned result-streaming, release-evidence, persistence, workflow, tests, and documentation identifiers. Prioritize public/persisted/shared contracts and preserve vendor/protocol names at adapters. -2. **Verification:** every source or contract repair requires exact-head tests, 100% required statement/branch/public-doc coverage, security checks, and current independent review under ordinary protection. -3. **Release evidence:** source versions and green development checks are not immutable release evidence; product claims must remain tied to actual release artifacts and reproducibility/provenance evidence. -4. **Consumer integration:** downstream hosts such as `contextual-orchestrator` and `naruon` consume released package contracts and provide authenticated tenant context; they must not copy package source or read package persistence as a cross-service shortcut. +1. **Dependency-root integration:** #233 remains outside protected `main`. Its normal merge requires all then-live required workflows and a qualifying independent approval; failed or missing central verdict publication cannot be replaced by a synthetic leaf status, self-approval, or routine bypass. +2. **Lifecycle/outbox convergence:** #319 remains a separate security source lineage. Its authority and this Result Application lineage require non-destructive convergence before a single integrated release claim can be made. +3. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, live authority admission, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. +4. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. Version/CHANGELOG/tag/package, SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat this work as released authority. +5. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, and cross-service SQL remain prohibited. ## Security / operability baseline -The current architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries for idempotent GET operations only, redacted diagnostics, deterministic checkpoint conflict behavior, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated regressions and doctoring rather than being hidden inside naming refactors. +The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. ## Evidence status -This baseline records repository truth visible on the current naming branch. It does not claim fresh exact-head workflow success, independent approval, release publication, buyer deployment, or downstream consumer validation until those artifacts exist on the unchanged final head. +Protected `main` and every open stack head remain separately authoritative. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, performance, approval, and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, or treat a green development head as a published release. From 9e0165ab5a411e7040fb1ed591c36b527949720f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 12 Sep 2026 05:03:04 +0900 Subject: [PATCH 16/57] docs: refresh canonical product gap authority --- docs/product-technical-gap-baseline.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index adf1fa4fc..458a7a8eb 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -20,11 +20,11 @@ Current invariants include tenant context before persistence/provider work; forc ## Result Application source authority -The canonical source/test parent is PR #277 on `fix/result-application-snapshot-b84f0c9`, exact `4937426e3bab44cb62d641de6205bd6da2d934fc`, based on dependency-root #233 exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. +The canonical source/test parent is PR #277 on `fix/result-application-snapshot-b84f0c9`, exact `db1fffb3bc309bf978470314524c585dc0dc48b9`, based on dependency-root #233 exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. -Hosted predecessor `ea1caf38caf0318e3f2613ab1d208e0236f93194` exposed a real verification defect after its non-force #233 merge: Release Acceptance succeeded and Python 3.10/3.12/3.14 plus PostgreSQL/container jobs passed, but CI `34105321157` failed the repository 100% coverage gate because four integer-budget defensive branches in `result_application.py` were uncovered. Test-only repair `4937426e3bab44cb62d641de6205bd6da2d934fc` covers exhausted byte budget, zero magnitude, negative-sign accounting, and conservative pre-materialization rejection without changing production behavior or public API. +Hosted predecessor `ea1caf38caf0318e3f2613ab1d208e0236f93194` exposed a real verification defect after its non-force #233 merge: Release Acceptance succeeded and Python 3.10/3.12/3.14 plus PostgreSQL/container jobs passed, but CI `34105321157` failed the repository 100% coverage gate because four integer-budget defensive branches in `result_application.py` were uncovered. Test-only repair `4937426e3bab44cb62d641de6205bd6da2d934fc` covered exhausted byte budget, zero magnitude, negative-sign accounting, and conservative pre-materialization rejection without changing production behavior or public API. Fresh review then found that the old huge-integer specimen did not independently prove that the conservative helper itself avoids decimal materialization. Current descendant `db1fffb3bc309bf978470314524c585dc0dc48b9` adds a direct helper regression that makes `str()` raise and verifies rejection occurs before conversion; the separate snapshot regression proves the guard is used by `_snapshot_json_record`. -Exact repaired parent evidence is GREEN: Release Acceptance `34107680525` and CI `34107680536` succeeded; coverage/package job `101696358568` recorded `1371 passed / 5 deselected`, production statements `3777/3777`, branches `1066/1066`, `result_application.py` `282/282` statements and `122/122` branches, 100% public docstrings, Ruff/lock/package success, and the Python 3.10/3.12/3.14 plus PostgreSQL/container jobs all succeeded. +Exact current parent evidence is GREEN: Release Acceptance `34108195163` and CI `34108195202` succeeded; coverage/package job `101698013309` recorded `1372 passed / 5 deselected`, owned production statements `3777/3777`, branches `1066/1066`, `result_application.py` `282/282` statements and `122/122` branches, 100% public docstrings, Ruff/lock/package success, and the Python 3.10/3.12/3.14 plus PostgreSQL/container jobs all succeeded. These receipts are branch evidence for #277 and do not transfer to this documentation child after a documentation commit. ## Documentation authority and convergence @@ -32,13 +32,13 @@ PR #324 on `fix/result-application-semantic-identifiers` is the documentation-on The previous documentation head inherited #277's uncovered-branch failure. It has been non-force restacked onto repaired #277 rather than rebased destructively or allowed to carry stale GREEN. Every documentation edit, including this baseline repair, requires new exact-head verification. -The active lifecycle/outbox security work in sibling PR #319 is not part of this branch ancestry. Therefore this document does not copy #319 source authority or claim its hosted evidence as current-branch truth. Final documentation convergence must occur only after the source topology legitimately integrates the relevant lifecycle/outbox delta; at that point the canonical baseline must preserve both Result Application and lifecycle/outbox evidence rather than selecting one lineage and dropping the other. +The active lifecycle/outbox security work in sibling PR #319 and its direct runtime-column authority child #336 are not part of this branch ancestry. Therefore this document does not copy their production/test source or claim their hosted evidence as current-branch truth. #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` closes runtime final-column parity and `atttypmod` authority on top of #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65`; both remain Draft candidate evidence until normal protected integration. Final documentation convergence must occur only after the source topology legitimately integrates the relevant lifecycle/outbox delta; at that point the canonical baseline must preserve both Result Application and lifecycle/outbox evidence rather than selecting one lineage and dropping the other. ## Current product / technical gaps -1. **Dependency-root integration:** #233 remains outside protected `main`. Its normal merge requires all then-live required workflows and a qualifying independent approval; failed or missing central verdict publication cannot be replaced by a synthetic leaf status, self-approval, or routine bypass. -2. **Lifecycle/outbox convergence:** #319 remains a separate security source lineage. Its authority and this Result Application lineage require non-destructive convergence before a single integrated release claim can be made. -3. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, live authority admission, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. +1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are GREEN, but then-required central CodeQL/OpenCode/Noema evidence and a qualifying independent approval still block normal merge. Central `.github#2040` is now non-force reconciled onto protected `.github/main@cb0872c9a20d5584703dffacca65c096fc034c6c` at exact `3b2de64c2c4c95c56d2f5099a480a0825304d038`; remaining CodeQL rollout/settlement defects belong to the central handler-first and coordinated-wake owner lanes #2051/#2056, not to a copied pg workflow or synthetic leaf status. +2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. +3. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. 4. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. Version/CHANGELOG/tag/package, SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat this work as released authority. 5. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, and cross-service SQL remain prohibited. @@ -48,4 +48,4 @@ The architecture requires bounded provider response processing, exact tenant val ## Evidence status -Protected `main` and every open stack head remain separately authoritative. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, performance, approval, and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, or treat a green development head as a published release. +Protected `main` and every open stack head remain separately authoritative. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, or treat a green development head as a published release. From aaf8bc8da78fd605ee26b087a714d2763bf50a49 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 12 Sep 2026 06:04:15 +0900 Subject: [PATCH 17/57] docs(gaps): separate evidence authority scopes --- docs/product-technical-gap-baseline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 458a7a8eb..d2782f758 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -48,4 +48,4 @@ The architecture requires bounded provider response processing, exact tenant val ## Evidence status -Protected `main` and every open stack head remain separately authoritative. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, or treat a green development head as a published release. +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, or treat a green development head as a published release. From 13774da3f9763da12fde8b21b6ec16a2d67e6399 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 13 Sep 2026 03:06:46 +0900 Subject: [PATCH 18/57] docs(gaps): refresh central integration authority --- docs/product-technical-gap-baseline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index d2782f758..8b23d721d 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,7 +36,7 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt ## Current product / technical gaps -1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are GREEN, but then-required central CodeQL/OpenCode/Noema evidence and a qualifying independent approval still block normal merge. Central `.github#2040` is now non-force reconciled onto protected `.github/main@cb0872c9a20d5584703dffacca65c096fc034c6c` at exact `3b2de64c2c4c95c56d2f5099a480a0825304d038`; remaining CodeQL rollout/settlement defects belong to the central handler-first and coordinated-wake owner lanes #2051/#2056, not to a copied pg workflow or synthetic leaf status. +1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are GREEN, but then-required central CodeQL/OpenCode/Noema evidence and a qualifying independent approval still block normal merge. The current central dependency is no longer the retired #2051/#2056 topology: protected-handler bootstrap `ContextualWisdomLab/.github#2106` remains the first integration prerequisite; after its normal protected integration, producer/consumer owner `ContextualWisdomLab/.github#2040` must ordinary/non-force merge-forward onto that protected commit, switch to the versioned protocol, and prove producer evidence before terminal consumer enforcement with exactly one run-wide settlement mutation on a new unchanged external canary. `ContextualWisdomLab/.github#2114` separately owns the bounded/redaction-safe OpenCode provider-failure telemetry required to diagnose model-backed review failures; its current Draft source/security evidence is unintegrated and does not replace the #2106/#2040 control-plane contract. These central gaps belong to their `.github` owners rather than copied pg workflows, synthetic leaf status, or no-op wake commits. 2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. 3. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. 4. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. Version/CHANGELOG/tag/package, SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat this work as released authority. From c25e593912806bb5ef2b9d1372375958c6aa2a20 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 13 Sep 2026 15:15:45 +0900 Subject: [PATCH 19/57] docs(gaps): refresh central prerequisite and release authority --- docs/product-technical-gap-baseline.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 8b23d721d..cc01279bf 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,11 +36,11 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt ## Current product / technical gaps -1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are GREEN, but then-required central CodeQL/OpenCode/Noema evidence and a qualifying independent approval still block normal merge. The current central dependency is no longer the retired #2051/#2056 topology: protected-handler bootstrap `ContextualWisdomLab/.github#2106` remains the first integration prerequisite; after its normal protected integration, producer/consumer owner `ContextualWisdomLab/.github#2040` must ordinary/non-force merge-forward onto that protected commit, switch to the versioned protocol, and prove producer evidence before terminal consumer enforcement with exactly one run-wide settlement mutation on a new unchanged external canary. `ContextualWisdomLab/.github#2114` separately owns the bounded/redaction-safe OpenCode provider-failure telemetry required to diagnose model-backed review failures; its current Draft source/security evidence is unintegrated and does not replace the #2106/#2040 control-plane contract. These central gaps belong to their `.github` owners rather than copied pg workflows, synthetic leaf status, or no-op wake commits. +1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is currently `64f483db9d052322c65bcdf1675d66138156f306`. The central prerequisite topology is now split across explicit owners rather than one leaf workaround: `.github#2079` is the Draft Noema verdict-contract lane and currently carries a test-first RED requiring a schema-representable nullable `finding_index` relation between confirmed adversarial probes and published findings; `.github#2094@5f90b418187482e7eee1d295d09145e899853925` owns trusted `uv`/materializer compatibility but its current Actions CodeQL compatibility receiver can still fail before the later successful dispatch, which is a control-plane settlement/order defect rather than an inferred uv-source finding; after #2094 normally integrates, stale `.github#1398@8ff7cc0969860a1473a57bbfe500ce3a023a41be` must ordinary/non-force reconcile the validated exact-HEAD Python lock contract before unchanged `contextual-orchestrator#995` is a valid consumer acceptance case. The CodeQL deployment-order path remains protected-handler bootstrap `.github#2106` before producer/consumer owner `.github#2040`; both must be reconciled against the then-current protected tip and prove fresh exact-head evidence rather than transferring predecessor receipts. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, or protection bypass is valid evidence. 2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. 3. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. -4. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. Version/CHANGELOG/tag/package, SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat this work as released authority. -5. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, and cross-service SQL remain prohibited. +4. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. `pg-llm-batch` currently has no GitHub Release. `contextual-orchestrator` also has no GitHub Release; its canonical release mechanism remains Draft in #1030 while packaging prerequisite #995 and the central exact-HEAD lock/materializer path remain unresolved. Version/CHANGELOG/tag/package, mandatory exact-commit SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat either branch state as released authority. +5. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. The normal dependency direction is owner RED → causal repair → exact-head GREEN → protected integration → immutable release → consumer pin/canary, not a leaf-side substitute for an unreleased foundation contract. ## Security / operability baseline @@ -48,4 +48,4 @@ The architecture requires bounded provider response processing, exact tenant val ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, or treat a green development head as a published release. +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, treat a green development head as a published release, or promote a central prerequisite's current branch state into pg product behavior. From e2f8d37845940066a05c106b53cb89037353b14e Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 13 Sep 2026 18:14:12 +0900 Subject: [PATCH 20/57] docs(gaps): distinguish current Noema owners --- docs/product-technical-gap-baseline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index cc01279bf..8b3770479 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,7 +36,7 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt ## Current product / technical gaps -1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is currently `64f483db9d052322c65bcdf1675d66138156f306`. The central prerequisite topology is now split across explicit owners rather than one leaf workaround: `.github#2079` is the Draft Noema verdict-contract lane and currently carries a test-first RED requiring a schema-representable nullable `finding_index` relation between confirmed adversarial probes and published findings; `.github#2094@5f90b418187482e7eee1d295d09145e899853925` owns trusted `uv`/materializer compatibility but its current Actions CodeQL compatibility receiver can still fail before the later successful dispatch, which is a control-plane settlement/order defect rather than an inferred uv-source finding; after #2094 normally integrates, stale `.github#1398@8ff7cc0969860a1473a57bbfe500ce3a023a41be` must ordinary/non-force reconcile the validated exact-HEAD Python lock contract before unchanged `contextual-orchestrator#995` is a valid consumer acceptance case. The CodeQL deployment-order path remains protected-handler bootstrap `.github#2106` before producer/consumer owner `.github#2040`; both must be reconciled against the then-current protected tip and prove fresh exact-head evidence rather than transferring predecessor receipts. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, or protection bypass is valid evidence. +1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is currently `64f483db9d052322c65bcdf1675d66138156f306`. The central prerequisite topology is split across explicit owners rather than one leaf workaround: `.github#2079` is the Draft Noema verdict-contract lane and still carries a test-first RED requiring a schema-representable nullable `finding_index` relation between confirmed adversarial probes and published findings. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` owns trusted `uv`/materializer compatibility; its current exact-head CodeQL actions/python/detect/dispatch and deterministic/security lanes are GREEN, so the earlier receiver-before-producer CodeQL failure is historical rather than the current material RED. The remaining required blocker on that head is `noema-review` run `34739350198`: its sidecar probed 16 of 24 candidates and found five ready routes, including both NVIDIA `llama-3.2-11b-vision-instruct` routes, while serving repeatedly selected deepseek routes and never attempted those ready llama alternatives. That multi-ready continuation defect is the behavior gap described by `.github#2140` ADR-0030; #2140 remains a docs-only Proposed lane on a stale base and is not yet an implementation fix. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain owned by open issue `.github#1948`, which must not be conflated with the continuation defect. After #2094 normally integrates, stale `.github#1398@8ff7cc0969860a1473a57bbfe500ce3a023a41be` must ordinary/non-force reconcile the validated exact-HEAD Python lock contract before unchanged `contextual-orchestrator#995` is a valid consumer acceptance case. The independent CodeQL deployment-order path remains protected-handler bootstrap `.github#2106` before producer/consumer owner `.github#2040`; both must prove fresh exact-head evidence against then-current protected authority rather than transferring predecessor receipts. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, or protection bypass is valid evidence. 2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. 3. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. 4. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. `pg-llm-batch` currently has no GitHub Release. `contextual-orchestrator` also has no GitHub Release; its canonical release mechanism remains Draft in #1030 while packaging prerequisite #995 and the central exact-HEAD lock/materializer path remain unresolved. Version/CHANGELOG/tag/package, mandatory exact-commit SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat either branch state as released authority. From 452a567ac7b288918aa7551c1e9108f751cb9b71 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 13 Sep 2026 20:09:50 +0900 Subject: [PATCH 21/57] docs(gaps): record protected-main diagnostic privacy gap --- docs/product-technical-gap-baseline.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 8b3770479..71ffe335f 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -16,7 +16,7 @@ **Aggregates / entities:** durable remote batch lifecycle row and checkpoint consumer state. **Value objects:** `BatchResultCheckpoint`, `CheckpointedBatchResultRecord`, result-application outcome, tenant/provider identities, and bounded accounting values. **Domain services:** provider batch gateway, checkpoint store, result application, lifecycle transition service, and backup/restore verification. **Domain evidence:** lifecycle observations, checkpoint advancement, and content-free recovery/release evidence. -Current invariants include tenant context before persistence/provider work; forced RLS for ordinary application roles; exact checkpoint monotonicity; same-transaction local effect plus checkpoint advance; bounded exact-JSON snapshots; fail-closed malformed or behavior-bearing authority; redacted diagnostics; and no arbitrary SQL or provider payload field becoming authorization/domain authority without validation and translation. +Integrated invariants include tenant context before persistence/provider work; forced RLS for ordinary application roles; exact checkpoint monotonicity; same-transaction local effect plus checkpoint advance; bounded exact-JSON snapshots; fail-closed malformed or behavior-bearing authority; and no arbitrary SQL or provider payload field becoming authorization/domain authority without validation and translation. Content-bounded/redacted diagnostic authority is a required product invariant but is not yet protected-main truth for every exception surface; the known `ValidationError` and token-limit diagnostic gaps are tracked explicitly below. ## Result Application source authority @@ -38,9 +38,10 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt 1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is currently `64f483db9d052322c65bcdf1675d66138156f306`. The central prerequisite topology is split across explicit owners rather than one leaf workaround: `.github#2079` is the Draft Noema verdict-contract lane and still carries a test-first RED requiring a schema-representable nullable `finding_index` relation between confirmed adversarial probes and published findings. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` owns trusted `uv`/materializer compatibility; its current exact-head CodeQL actions/python/detect/dispatch and deterministic/security lanes are GREEN, so the earlier receiver-before-producer CodeQL failure is historical rather than the current material RED. The remaining required blocker on that head is `noema-review` run `34739350198`: its sidecar probed 16 of 24 candidates and found five ready routes, including both NVIDIA `llama-3.2-11b-vision-instruct` routes, while serving repeatedly selected deepseek routes and never attempted those ready llama alternatives. That multi-ready continuation defect is the behavior gap described by `.github#2140` ADR-0030; #2140 remains a docs-only Proposed lane on a stale base and is not yet an implementation fix. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain owned by open issue `.github#1948`, which must not be conflated with the continuation defect. After #2094 normally integrates, stale `.github#1398@8ff7cc0969860a1473a57bbfe500ce3a023a41be` must ordinary/non-force reconcile the validated exact-HEAD Python lock contract before unchanged `contextual-orchestrator#995` is a valid consumer acceptance case. The independent CodeQL deployment-order path remains protected-handler bootstrap `.github#2106` before producer/consumer owner `.github#2040`; both must prove fresh exact-head evidence against then-current protected authority rather than transferring predecessor receipts. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, or protection bypass is valid evidence. 2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. -3. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. -4. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. `pg-llm-batch` currently has no GitHub Release. `contextual-orchestrator` also has no GitHub Release; its canonical release mechanism remains Draft in #1030 while packaging prerequisite #995 and the central exact-HEAD lock/materializer path remain unresolved. Version/CHANGELOG/tag/package, mandatory exact-commit SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat either branch state as released authority. -5. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. The normal dependency direction is owner RED → causal repair → exact-head GREEN → protected integration → immutable release → consumer pin/canary, not a leaf-side substitute for an unreleased foundation contract. +3. **Diagnostic privacy:** protected `main` still copies caller-controlled values into package-owned exception authority. `ValidationError` renders and retains rejected `value` by default (#132), while `TokenLimitExceededError` copies raw `batch_id` into both exception text and structured `details` (#304). Draft #202 remains the canonical `exceptions.py` privacy writer at `cb4689fb18685e32d920aa84ff388f9baf52da6a`; its branch-only candidate redacts arbitrary rejected `ValidationError.value` unless an explicitly bounded `safe_value` is supplied, but its stale ten-file surface includes `orchestrator.py`. Fresh writer inventory also finds active Draft #323 changing `orchestrator.py`, so #202 must not be blindly merge-forwarded or expanded into #304 while that overlap remains unresolved. The accepted privacy repair must keep arbitrary rejected content and raw/high-cardinality batch identity out of `str(error)`, `repr(error)`, `repr(error.args)`, and package-owned structured details by default, preserve exact numeric token accounting, reject behavior-bearing renderers, and not substitute a stable hash that creates a new correlation/retention contract. This is an unresolved protected-main buyer/security gap, not a claim that branch-only #202 behavior is shipped. +4. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. +5. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. `pg-llm-batch` currently has no GitHub Release. `contextual-orchestrator` also has no GitHub Release; its canonical release mechanism remains Draft in #1030 while packaging prerequisite #995 and the central exact-HEAD lock/materializer path remain unresolved. Version/CHANGELOG/tag/package, mandatory exact-commit SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat either branch state as released authority. +6. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. The normal dependency direction is owner RED → causal repair → exact-head GREEN → protected integration → immutable release → consumer pin/canary, not a leaf-side substitute for an unreleased foundation contract. ## Security / operability baseline @@ -48,4 +49,4 @@ The architecture requires bounded provider response processing, exact tenant val ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, treat a green development head as a published release, or promote a central prerequisite's current branch state into pg product behavior. +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, diagnostic-privacy, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, treat a green development head as a published release, or promote a central prerequisite's current branch state into pg product behavior. From 79b7347ae822a8d95cf3831bba5ea8390cfa9ee1 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 13 Sep 2026 21:43:19 +0900 Subject: [PATCH 22/57] docs(gaps): refresh diagnostic privacy lineage --- docs/product-technical-gap-baseline.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 71ffe335f..ea06ede63 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -38,7 +38,7 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt 1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is currently `64f483db9d052322c65bcdf1675d66138156f306`. The central prerequisite topology is split across explicit owners rather than one leaf workaround: `.github#2079` is the Draft Noema verdict-contract lane and still carries a test-first RED requiring a schema-representable nullable `finding_index` relation between confirmed adversarial probes and published findings. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` owns trusted `uv`/materializer compatibility; its current exact-head CodeQL actions/python/detect/dispatch and deterministic/security lanes are GREEN, so the earlier receiver-before-producer CodeQL failure is historical rather than the current material RED. The remaining required blocker on that head is `noema-review` run `34739350198`: its sidecar probed 16 of 24 candidates and found five ready routes, including both NVIDIA `llama-3.2-11b-vision-instruct` routes, while serving repeatedly selected deepseek routes and never attempted those ready llama alternatives. That multi-ready continuation defect is the behavior gap described by `.github#2140` ADR-0030; #2140 remains a docs-only Proposed lane on a stale base and is not yet an implementation fix. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain owned by open issue `.github#1948`, which must not be conflated with the continuation defect. After #2094 normally integrates, stale `.github#1398@8ff7cc0969860a1473a57bbfe500ce3a023a41be` must ordinary/non-force reconcile the validated exact-HEAD Python lock contract before unchanged `contextual-orchestrator#995` is a valid consumer acceptance case. The independent CodeQL deployment-order path remains protected-handler bootstrap `.github#2106` before producer/consumer owner `.github#2040`; both must prove fresh exact-head evidence against then-current protected authority rather than transferring predecessor receipts. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, or protection bypass is valid evidence. 2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. -3. **Diagnostic privacy:** protected `main` still copies caller-controlled values into package-owned exception authority. `ValidationError` renders and retains rejected `value` by default (#132), while `TokenLimitExceededError` copies raw `batch_id` into both exception text and structured `details` (#304). Draft #202 remains the canonical `exceptions.py` privacy writer at `cb4689fb18685e32d920aa84ff388f9baf52da6a`; its branch-only candidate redacts arbitrary rejected `ValidationError.value` unless an explicitly bounded `safe_value` is supplied, but its stale ten-file surface includes `orchestrator.py`. Fresh writer inventory also finds active Draft #323 changing `orchestrator.py`, so #202 must not be blindly merge-forwarded or expanded into #304 while that overlap remains unresolved. The accepted privacy repair must keep arbitrary rejected content and raw/high-cardinality batch identity out of `str(error)`, `repr(error)`, `repr(error.args)`, and package-owned structured details by default, preserve exact numeric token accounting, reject behavior-bearing renderers, and not substitute a stable hash that creates a new correlation/retention contract. This is an unresolved protected-main buyer/security gap, not a claim that branch-only #202 behavior is shipped. +3. **Diagnostic privacy and warning hygiene:** protected `main` still copies caller-controlled values into package-owned exception authority. `ValidationError` renders and retains rejected `value` by default (#132), while `TokenLimitExceededError` copies raw `batch_id` into both exception text and structured `details` (#304). The previous source-writer overlap is no longer current: Draft #202 is exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33`, ordinary/non-force stacked directly on #323 exact `34858ef2f96307273853901bef932ec2958e4931`, and its effective production delta is confined to `pg_llm_batch/exceptions.py` plus privacy-focused tests rather than stale `orchestrator.py` ownership. #202 exact-head CI `34756635313` and Release Acceptance `34756635333` are branch-local GREEN. Draft #344 is the serialized #304 child of #202 at exact `03be5eaca49c7c76922df8545dcc4f72842567e8`; it keeps `batch_id` in the constructor for compatibility but neither truth-tests, renders, hashes, nor retains it, while preserving exact `current_tokens`, `limit_tokens`, `excess_tokens`, and `TOKEN_LIMIT_EXCEEDED`. Its test contract also rejects behavior-bearing identifier authority. Exact-head CI `34757663693` and Release Acceptance `34757663694` are GREEN with 100% public docstrings and 100.00% production statement/branch coverage (`4729` statements, `1348` branches, zero misses/partials). This is not shipped truth: #202/#344 remain Draft descendants outside protected main. Their Python 3.14 quality runs also expose five inherited warnings that are not waived: four synthetic schema-close finalizer warnings are canonically repaired by Draft #251, and the independent compose/runpy RuntimeWarning by Draft #252. #252's exact GREEN proves the combined `#251 -> #252` warning lineage reaches zero warnings. Privacy and warning lanes must converge through their existing owners after #233 rather than copying sibling fixes or suppressing diagnostics. 4. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. 5. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. `pg-llm-batch` currently has no GitHub Release. `contextual-orchestrator` also has no GitHub Release; its canonical release mechanism remains Draft in #1030 while packaging prerequisite #995 and the central exact-HEAD lock/materializer path remain unresolved. Version/CHANGELOG/tag/package, mandatory exact-commit SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat either branch state as released authority. 6. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. The normal dependency direction is owner RED → causal repair → exact-head GREEN → protected integration → immutable release → consumer pin/canary, not a leaf-side substitute for an unreleased foundation contract. @@ -49,4 +49,4 @@ The architecture requires bounded provider response processing, exact tenant val ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, diagnostic-privacy, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, treat a green development head as a published release, or promote a central prerequisite's current branch state into pg product behavior. +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, diagnostic-privacy, warning-hygiene, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, treat a green development head as a published release, or promote a central prerequisite's current branch state into pg product behavior. From 9b49ac3132913d55f641a7db389340e27bfc1834 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 13 Sep 2026 21:45:28 +0900 Subject: [PATCH 23/57] docs(gaps): refresh Noema relation repair state --- docs/product-technical-gap-baseline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index ea06ede63..46c90664e 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,7 +36,7 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt ## Current product / technical gaps -1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is currently `64f483db9d052322c65bcdf1675d66138156f306`. The central prerequisite topology is split across explicit owners rather than one leaf workaround: `.github#2079` is the Draft Noema verdict-contract lane and still carries a test-first RED requiring a schema-representable nullable `finding_index` relation between confirmed adversarial probes and published findings. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` owns trusted `uv`/materializer compatibility; its current exact-head CodeQL actions/python/detect/dispatch and deterministic/security lanes are GREEN, so the earlier receiver-before-producer CodeQL failure is historical rather than the current material RED. The remaining required blocker on that head is `noema-review` run `34739350198`: its sidecar probed 16 of 24 candidates and found five ready routes, including both NVIDIA `llama-3.2-11b-vision-instruct` routes, while serving repeatedly selected deepseek routes and never attempted those ready llama alternatives. That multi-ready continuation defect is the behavior gap described by `.github#2140` ADR-0030; #2140 remains a docs-only Proposed lane on a stale base and is not yet an implementation fix. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain owned by open issue `.github#1948`, which must not be conflated with the continuation defect. After #2094 normally integrates, stale `.github#1398@8ff7cc0969860a1473a57bbfe500ce3a023a41be` must ordinary/non-force reconcile the validated exact-HEAD Python lock contract before unchanged `contextual-orchestrator#995` is a valid consumer acceptance case. The independent CodeQL deployment-order path remains protected-handler bootstrap `.github#2106` before producer/consumer owner `.github#2040`; both must prove fresh exact-head evidence against then-current protected authority rather than transferring predecessor receipts. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, or protection bypass is valid evidence. +1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is currently `64f483db9d052322c65bcdf1675d66138156f306`. The central prerequisite topology is split across explicit owners rather than one leaf workaround. `.github#2079` has advanced from its intentional relation RED to exact source-repaired head `9dccfaa0776950498e557390a2fa8d6c34e0baf4`, Ready/open/mergeable on current protected main: the structured-output schema now requires nullable `finding_index`; confirmed probes must bind a valid finding at the same `(file,line,side)`, falsified probes must bind explicit null, and the deterministic validator independently rechecks type/range/location/outcome. Its fresh Security Scan, Semgrep, and Python Security runs are terminal GREEN; replacement CodeQL generated by the Ready event is still in progress, so #2079 is review-admission evidence rather than integrated authority. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` owns trusted `uv`/materializer compatibility; its current exact-head CodeQL actions/python/detect/dispatch and deterministic/security lanes are GREEN, so the earlier receiver-before-producer CodeQL failure is historical rather than the current material RED. Its remaining required blocker is `noema-review` run `34739350198`: the sidecar probed 16 of 24 candidates and found five ready routes, including both NVIDIA `llama-3.2-11b-vision-instruct` routes, while serving repeatedly selected deepseek routes and never attempted those ready llama alternatives. That multi-ready continuation defect is the behavior gap described by `.github#2140` ADR-0030; #2140 remains a docs-only Proposed lane on a stale base and is not yet an implementation fix. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain owned by open issue `.github#1948`, which must not be conflated with the continuation defect. After #2079 and #2094 normally integrate as their live gates permit, stale `.github#1398@8ff7cc0969860a1473a57bbfe500ce3a023a41be` must ordinary/non-force reconcile the validated exact-HEAD Python lock contract before unchanged `contextual-orchestrator#995` is a valid consumer acceptance case. The independent CodeQL deployment-order path remains protected-handler bootstrap `.github#2106` before producer/consumer owner `.github#2040`; both must prove fresh exact-head evidence against then-current protected authority rather than transferring predecessor receipts. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, or protection bypass is valid evidence. 2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. 3. **Diagnostic privacy and warning hygiene:** protected `main` still copies caller-controlled values into package-owned exception authority. `ValidationError` renders and retains rejected `value` by default (#132), while `TokenLimitExceededError` copies raw `batch_id` into both exception text and structured `details` (#304). The previous source-writer overlap is no longer current: Draft #202 is exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33`, ordinary/non-force stacked directly on #323 exact `34858ef2f96307273853901bef932ec2958e4931`, and its effective production delta is confined to `pg_llm_batch/exceptions.py` plus privacy-focused tests rather than stale `orchestrator.py` ownership. #202 exact-head CI `34756635313` and Release Acceptance `34756635333` are branch-local GREEN. Draft #344 is the serialized #304 child of #202 at exact `03be5eaca49c7c76922df8545dcc4f72842567e8`; it keeps `batch_id` in the constructor for compatibility but neither truth-tests, renders, hashes, nor retains it, while preserving exact `current_tokens`, `limit_tokens`, `excess_tokens`, and `TOKEN_LIMIT_EXCEEDED`. Its test contract also rejects behavior-bearing identifier authority. Exact-head CI `34757663693` and Release Acceptance `34757663694` are GREEN with 100% public docstrings and 100.00% production statement/branch coverage (`4729` statements, `1348` branches, zero misses/partials). This is not shipped truth: #202/#344 remain Draft descendants outside protected main. Their Python 3.14 quality runs also expose five inherited warnings that are not waived: four synthetic schema-close finalizer warnings are canonically repaired by Draft #251, and the independent compose/runpy RuntimeWarning by Draft #252. #252's exact GREEN proves the combined `#251 -> #252` warning lineage reaches zero warnings. Privacy and warning lanes must converge through their existing owners after #233 rather than copying sibling fixes or suppressing diagnostics. 4. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. From 2985486b6680ddfceea38f813d41ae62b8e824c0 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sun, 13 Sep 2026 23:05:52 +0900 Subject: [PATCH 24/57] docs(gap): refresh central review and release owners --- docs/product-technical-gap-baseline.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 46c90664e..2a160fb4d 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,11 +36,11 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt ## Current product / technical gaps -1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is currently `64f483db9d052322c65bcdf1675d66138156f306`. The central prerequisite topology is split across explicit owners rather than one leaf workaround. `.github#2079` has advanced from its intentional relation RED to exact source-repaired head `9dccfaa0776950498e557390a2fa8d6c34e0baf4`, Ready/open/mergeable on current protected main: the structured-output schema now requires nullable `finding_index`; confirmed probes must bind a valid finding at the same `(file,line,side)`, falsified probes must bind explicit null, and the deterministic validator independently rechecks type/range/location/outcome. Its fresh Security Scan, Semgrep, and Python Security runs are terminal GREEN; replacement CodeQL generated by the Ready event is still in progress, so #2079 is review-admission evidence rather than integrated authority. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` owns trusted `uv`/materializer compatibility; its current exact-head CodeQL actions/python/detect/dispatch and deterministic/security lanes are GREEN, so the earlier receiver-before-producer CodeQL failure is historical rather than the current material RED. Its remaining required blocker is `noema-review` run `34739350198`: the sidecar probed 16 of 24 candidates and found five ready routes, including both NVIDIA `llama-3.2-11b-vision-instruct` routes, while serving repeatedly selected deepseek routes and never attempted those ready llama alternatives. That multi-ready continuation defect is the behavior gap described by `.github#2140` ADR-0030; #2140 remains a docs-only Proposed lane on a stale base and is not yet an implementation fix. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain owned by open issue `.github#1948`, which must not be conflated with the continuation defect. After #2079 and #2094 normally integrate as their live gates permit, stale `.github#1398@8ff7cc0969860a1473a57bbfe500ce3a023a41be` must ordinary/non-force reconcile the validated exact-HEAD Python lock contract before unchanged `contextual-orchestrator#995` is a valid consumer acceptance case. The independent CodeQL deployment-order path remains protected-handler bootstrap `.github#2106` before producer/consumer owner `.github#2040`; both must prove fresh exact-head evidence against then-current protected authority rather than transferring predecessor receipts. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, or protection bypass is valid evidence. +1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is now exact `78393ea901efc0d57b35dd1e383e473425b7c1da`. `.github#2079` has repaired the finding/probe relation source defect at exact `9dccfaa0776950498e557390a2fa8d6c34e0baf4`: structured output requires nullable `finding_index`; confirmed probes must bind a valid finding at the same `(file,line,side)`, falsified probes must bind explicit null, and the deterministic validator rechecks type/range/location/outcome. It remains Ready/open with PR base metadata on predecessor `64f483db9d052322c65bcdf1675d66138156f306`, so its source repair is valid candidate delta but its protected-base evidence is stale and must be reconciled ordinary/non-force before integration. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` likewise retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306`; it must reconcile to current protected central authority rather than receive a leaf-side wake commit. Its historical Noema run `34739350198` exposed a separate serving defect: five routes were preflight-ready, but a timeout on the selected route ended the virtual `orchestrator/free` request without trying other ready candidates. That behavior now has an implementation owner in `contextual-orchestrator#1176@a9cb8c6749008904815c663ebd8f8fff7099d6ae`, based directly on protected CO `main@767e67fbc6b881a452761f32abb69b9971b9b03b`: virtual selectors advance across ambiguous transport timeouts while explicit concrete-model requests remain single-shot/fail-closed. Exact-head Security Scan, Semgrep, and Security and Quality are GREEN; CodeQL PR is still failing, so #1176 is not protected or released authority. `.github#2140` remains useful architectural/progress-boundary work, but it is no longer the only implementation path for this multi-ready timeout case. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain separate owner work under `.github#1948`. The independent CodeQL deployment-order lane has also moved: `.github#2106` is now exact `db34e6b9d739c5ef228bacdc2efaa5f3a9238356`, Ready/open/mergeable directly on current protected central `main@78393ea901efc0d57b35dd1e383e473425b7c1da`; after that backward-compatible handler bootstrap integrates normally, Draft `.github#2040@85522306949bada2b5939608dc911f6374125f1b` must ordinary/non-force reconcile from stale base `fb17ef556f94f673234aa557254ae52779e9a7b0`, switch to the versioned protocol, and reacquire exact-head terminal evidence plus a fresh unchanged external canary. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, manual rerun loop, or protection bypass is valid evidence. 2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. 3. **Diagnostic privacy and warning hygiene:** protected `main` still copies caller-controlled values into package-owned exception authority. `ValidationError` renders and retains rejected `value` by default (#132), while `TokenLimitExceededError` copies raw `batch_id` into both exception text and structured `details` (#304). The previous source-writer overlap is no longer current: Draft #202 is exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33`, ordinary/non-force stacked directly on #323 exact `34858ef2f96307273853901bef932ec2958e4931`, and its effective production delta is confined to `pg_llm_batch/exceptions.py` plus privacy-focused tests rather than stale `orchestrator.py` ownership. #202 exact-head CI `34756635313` and Release Acceptance `34756635333` are branch-local GREEN. Draft #344 is the serialized #304 child of #202 at exact `03be5eaca49c7c76922df8545dcc4f72842567e8`; it keeps `batch_id` in the constructor for compatibility but neither truth-tests, renders, hashes, nor retains it, while preserving exact `current_tokens`, `limit_tokens`, `excess_tokens`, and `TOKEN_LIMIT_EXCEEDED`. Its test contract also rejects behavior-bearing identifier authority. Exact-head CI `34757663693` and Release Acceptance `34757663694` are GREEN with 100% public docstrings and 100.00% production statement/branch coverage (`4729` statements, `1348` branches, zero misses/partials). This is not shipped truth: #202/#344 remain Draft descendants outside protected main. Their Python 3.14 quality runs also expose five inherited warnings that are not waived: four synthetic schema-close finalizer warnings are canonically repaired by Draft #251, and the independent compose/runpy RuntimeWarning by Draft #252. #252's exact GREEN proves the combined `#251 -> #252` warning lineage reaches zero warnings. Privacy and warning lanes must converge through their existing owners after #233 rather than copying sibling fixes or suppressing diagnostics. 4. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. -5. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. `pg-llm-batch` currently has no GitHub Release. `contextual-orchestrator` also has no GitHub Release; its canonical release mechanism remains Draft in #1030 while packaging prerequisite #995 and the central exact-HEAD lock/materializer path remain unresolved. Version/CHANGELOG/tag/package, mandatory exact-commit SBOM, provenance, reproducibility, rollback evidence, and an actual protected-head release remain required before downstream consumers treat either branch state as released authority. +5. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. Fresh GitHub Release reads still return zero releases for both `pg-llm-batch` and `contextual-orchestrator`. Protected CO `main` is exact `767e67fbc6b881a452761f32abb69b9971b9b03b`, but packaging prerequisite #995 remains exact `29b7f5457ee6a9c2a1f25f1e564f798d419bacc9` on stale base `012beaacd0631f8cd3391c77744eeb626269b5de`, and canonical release owner #1030 remains Draft exact `b51009c8b5b6c9e79672e412a87e5b4609f42173` on much older base `414f22973658c4ddc3d4320fcf7acd9b4e8ba991`. Central `.github#2163` consuming protected CO source `767e67fb...` fixes the implicit-timeout incident but does not convert that source SHA into a released API/client/schema contract. #995 and #1030 must reconcile through ordinary protected ancestry and the release lane must actually publish version/CHANGELOG/tag/package, exact-commit SBOM, provenance, reproducibility and rollback evidence before central or pg consumers treat CO identity as released authority. 6. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. The normal dependency direction is owner RED → causal repair → exact-head GREEN → protected integration → immutable release → consumer pin/canary, not a leaf-side substitute for an unreleased foundation contract. ## Security / operability baseline From 2b492686cffc2a105b56be30e925d5286a5abd6e Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 14 Sep 2026 01:07:25 +0900 Subject: [PATCH 25/57] docs(gap): record current central acceptance blockers --- docs/product-technical-gap-baseline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 2a160fb4d..b4b2c9936 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,7 +36,7 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt ## Current product / technical gaps -1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is now exact `78393ea901efc0d57b35dd1e383e473425b7c1da`. `.github#2079` has repaired the finding/probe relation source defect at exact `9dccfaa0776950498e557390a2fa8d6c34e0baf4`: structured output requires nullable `finding_index`; confirmed probes must bind a valid finding at the same `(file,line,side)`, falsified probes must bind explicit null, and the deterministic validator rechecks type/range/location/outcome. It remains Ready/open with PR base metadata on predecessor `64f483db9d052322c65bcdf1675d66138156f306`, so its source repair is valid candidate delta but its protected-base evidence is stale and must be reconciled ordinary/non-force before integration. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` likewise retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306`; it must reconcile to current protected central authority rather than receive a leaf-side wake commit. Its historical Noema run `34739350198` exposed a separate serving defect: five routes were preflight-ready, but a timeout on the selected route ended the virtual `orchestrator/free` request without trying other ready candidates. That behavior now has an implementation owner in `contextual-orchestrator#1176@a9cb8c6749008904815c663ebd8f8fff7099d6ae`, based directly on protected CO `main@767e67fbc6b881a452761f32abb69b9971b9b03b`: virtual selectors advance across ambiguous transport timeouts while explicit concrete-model requests remain single-shot/fail-closed. Exact-head Security Scan, Semgrep, and Security and Quality are GREEN; CodeQL PR is still failing, so #1176 is not protected or released authority. `.github#2140` remains useful architectural/progress-boundary work, but it is no longer the only implementation path for this multi-ready timeout case. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain separate owner work under `.github#1948`. The independent CodeQL deployment-order lane has also moved: `.github#2106` is now exact `db34e6b9d739c5ef228bacdc2efaa5f3a9238356`, Ready/open/mergeable directly on current protected central `main@78393ea901efc0d57b35dd1e383e473425b7c1da`; after that backward-compatible handler bootstrap integrates normally, Draft `.github#2040@85522306949bada2b5939608dc911f6374125f1b` must ordinary/non-force reconcile from stale base `fb17ef556f94f673234aa557254ae52779e9a7b0`, switch to the versioned protocol, and reacquire exact-head terminal evidence plus a fresh unchanged external canary. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, manual rerun loop, or protection bypass is valid evidence. +1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is exact `78393ea901efc0d57b35dd1e383e473425b7c1da`. `.github#2079` has repaired the finding/probe relation source defect at exact `9dccfaa0776950498e557390a2fa8d6c34e0baf4`, but it is now **Draft** because Required OpenCode Review `34757059796` failed deterministic `coverage-evidence` at touched-callable docstring coverage **76.47% (13/17; threshold 80%)**. Fresh diff inspection confirms the missing documentation is confined to four nested fixture methods in `tests/test_noema_review_gate.py`: `Response.__enter__`, `Response.__exit__`, `Response.read`, and `Opener.open`. The minimum causal repair is meaningful docstrings on those four methods followed by fresh exact-head evidence; lowering the threshold, manufacturing a wake commit, or retrying the model path around the deterministic RED is not valid. The branch also retains stale base metadata `64f483db9d052322c65bcdf1675d66138156f306`, so source GREEN must be followed by ordinary/non-force reconciliation to current protected central main and fresh current-base gates. Scheduler/RCA owner `.github#2170@d3f1d0264912e74b897fdf2a0a6085100de4e40a` is directly based on `78393ea...` and has repaired the control-plane blind spot that previously excluded `Required OpenCode Review / coverage-evidence` from bounded RCA while continuing to exclude `opencode-review` and other/unknown OpenCode-family workflows. Its SAST, Security Scan, and Agent Review Runtime Quality lanes are terminal GREEN, while CodeQL remains queued and Python Security is non-terminal; its evidence does not transfer to #2079. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` likewise retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306`; it must reconcile to current protected central authority rather than receive a leaf-side wake commit. Its historical Noema run `34739350198` exposed a separate serving defect: five routes were preflight-ready, but a timeout on the selected route ended the virtual `orchestrator/free` request without trying other ready candidates. That behavior now has an implementation owner in `contextual-orchestrator#1176@a9cb8c6749008904815c663ebd8f8fff7099d6ae`, based directly on protected CO `main@767e67fbc6b881a452761f32abb69b9971b9b03b`: virtual selectors advance across ambiguous transport timeouts while explicit concrete-model requests remain single-shot/fail-closed. Exact-head Security Scan, Semgrep, and Security and Quality are GREEN; CodeQL PR `34759495194` is terminal FAILURE in the central compatibility-enforcement family, so no CO source/SARIF defect is inferred from that gate alone and #1176 remains neither protected nor released authority. `.github#2140` remains useful architectural/progress-boundary work, but it is no longer the only implementation path for this multi-ready timeout case. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain separate owner work under `.github#1948`. The independent CodeQL deployment-order lane is also terminally characterized: `.github#2106@db34e6b9d739c5ef228bacdc2efaa5f3a9238356` is Ready/open/mergeable directly on current protected central `main@78393ea...`, but CodeQL PR `34761450697` is terminal FAILURE. Language detection succeeded; both compatibility receivers read the current-head dispatch verdict and failed only at `Release runner or enforce current-head CodeQL verdict`; only after those terminal receiver failures did `Dispatch current-head CodeQL scan` succeed. This is producer-after-terminal-consumer/bootstrap evidence rather than a source/SARIF finding. Repair therefore remains `#2106 -> normal protected integration -> Draft #2040@85522306949bada2b5939608dc911f6374125f1b ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence and unchanged external canary`. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, manual rerun loop, or protection bypass is valid evidence. 2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. 3. **Diagnostic privacy and warning hygiene:** protected `main` still copies caller-controlled values into package-owned exception authority. `ValidationError` renders and retains rejected `value` by default (#132), while `TokenLimitExceededError` copies raw `batch_id` into both exception text and structured `details` (#304). The previous source-writer overlap is no longer current: Draft #202 is exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33`, ordinary/non-force stacked directly on #323 exact `34858ef2f96307273853901bef932ec2958e4931`, and its effective production delta is confined to `pg_llm_batch/exceptions.py` plus privacy-focused tests rather than stale `orchestrator.py` ownership. #202 exact-head CI `34756635313` and Release Acceptance `34756635333` are branch-local GREEN. Draft #344 is the serialized #304 child of #202 at exact `03be5eaca49c7c76922df8545dcc4f72842567e8`; it keeps `batch_id` in the constructor for compatibility but neither truth-tests, renders, hashes, nor retains it, while preserving exact `current_tokens`, `limit_tokens`, `excess_tokens`, and `TOKEN_LIMIT_EXCEEDED`. Its test contract also rejects behavior-bearing identifier authority. Exact-head CI `34757663693` and Release Acceptance `34757663694` are GREEN with 100% public docstrings and 100.00% production statement/branch coverage (`4729` statements, `1348` branches, zero misses/partials). This is not shipped truth: #202/#344 remain Draft descendants outside protected main. Their Python 3.14 quality runs also expose five inherited warnings that are not waived: four synthetic schema-close finalizer warnings are canonically repaired by Draft #251, and the independent compose/runpy RuntimeWarning by Draft #252. #252's exact GREEN proves the combined `#251 -> #252` warning lineage reaches zero warnings. Privacy and warning lanes must converge through their existing owners after #233 rather than copying sibling fixes or suppressing diagnostics. 4. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. From 1609e02c81b8ffe55f11167b92e6efece23ccedb Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 14 Sep 2026 04:03:04 +0900 Subject: [PATCH 26/57] docs(gap): refresh live central and release prerequisites --- docs/product-technical-gap-baseline.md | 43 +++++++++++++++++--------- 1 file changed, 29 insertions(+), 14 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index b4b2c9936..27669919e 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -16,37 +16,52 @@ **Aggregates / entities:** durable remote batch lifecycle row and checkpoint consumer state. **Value objects:** `BatchResultCheckpoint`, `CheckpointedBatchResultRecord`, result-application outcome, tenant/provider identities, and bounded accounting values. **Domain services:** provider batch gateway, checkpoint store, result application, lifecycle transition service, and backup/restore verification. **Domain evidence:** lifecycle observations, checkpoint advancement, and content-free recovery/release evidence. -Integrated invariants include tenant context before persistence/provider work; forced RLS for ordinary application roles; exact checkpoint monotonicity; same-transaction local effect plus checkpoint advance; bounded exact-JSON snapshots; fail-closed malformed or behavior-bearing authority; and no arbitrary SQL or provider payload field becoming authorization/domain authority without validation and translation. Content-bounded/redacted diagnostic authority is a required product invariant but is not yet protected-main truth for every exception surface; the known `ValidationError` and token-limit diagnostic gaps are tracked explicitly below. +The protected contract requires tenant context before persistence/provider work; tenant scope is selected only at an authenticated and authorized host boundary; transaction-local parameterized `set_config` binds that scope; lifecycle lookup/conflict/index authority is tenant-qualified; RLS remains enabled and forced for `NOSUPERUSER NOBYPASSRLS` application roles; migration restores forced RLS atomically; package and Docker schemas remain byte-identical; automatic provider retries remain restricted to reviewed idempotent GET semantics; production statement, branch, and public-docstring coverage remain 100%. ## Result Application source authority The canonical source/test parent is PR #277 on `fix/result-application-snapshot-b84f0c9`, exact `db1fffb3bc309bf978470314524c585dc0dc48b9`, based on dependency-root #233 exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. -Hosted predecessor `ea1caf38caf0318e3f2613ab1d208e0236f93194` exposed a real verification defect after its non-force #233 merge: Release Acceptance succeeded and Python 3.10/3.12/3.14 plus PostgreSQL/container jobs passed, but CI `34105321157` failed the repository 100% coverage gate because four integer-budget defensive branches in `result_application.py` were uncovered. Test-only repair `4937426e3bab44cb62d641de6205bd6da2d934fc` covered exhausted byte budget, zero magnitude, negative-sign accounting, and conservative pre-materialization rejection without changing production behavior or public API. Fresh review then found that the old huge-integer specimen did not independently prove that the conservative helper itself avoids decimal materialization. Current descendant `db1fffb3bc309bf978470314524c585dc0dc48b9` adds a direct helper regression that makes `str()` raise and verifies rejection occurs before conversion; the separate snapshot regression proves the guard is used by `_snapshot_json_record`. - -Exact current parent evidence is GREEN: Release Acceptance `34108195163` and CI `34108195202` succeeded; coverage/package job `101698013309` recorded `1372 passed / 5 deselected`, owned production statements `3777/3777`, branches `1066/1066`, `result_application.py` `282/282` statements and `122/122` branches, 100% public docstrings, Ruff/lock/package success, and the Python 3.10/3.12/3.14 plus PostgreSQL/container jobs all succeeded. These receipts are branch evidence for #277 and do not transfer to this documentation child after a documentation commit. +#277 already owns the Result Application source/test fixes, including the integer-budget regressions that prove bounded snapshot rejection occurs before huge decimal materialization. Its current branch-local repository evidence is GREEN. Those receipts do not transfer across descendant commits or constitute protected-main integration. ## Documentation authority and convergence PR #324 on `fix/result-application-semantic-identifiers` is the documentation-only child of #277. It owns the Result Application naming explanation in `ARCHITECTURE.md`, `CHANGELOG.md`, `docs/doctoring/result-application-semantic-identifiers.md`, and this baseline; it must not regain production/test authority already owned by #277. -The previous documentation head inherited #277's uncovered-branch failure. It has been non-force restacked onto repaired #277 rather than rebased destructively or allowed to carry stale GREEN. Every documentation edit, including this baseline repair, requires new exact-head verification. - -The active lifecycle/outbox security work in sibling PR #319 and its direct runtime-column authority child #336 are not part of this branch ancestry. Therefore this document does not copy their production/test source or claim their hosted evidence as current-branch truth. #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` closes runtime final-column parity and `atttypmod` authority on top of #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65`; both remain Draft candidate evidence until normal protected integration. Final documentation convergence must occur only after the source topology legitimately integrates the relevant lifecycle/outbox delta; at that point the canonical baseline must preserve both Result Application and lifecycle/outbox evidence rather than selecting one lineage and dropping the other. +The active lifecycle/outbox security work in sibling PR #319 and its direct runtime-column authority child #336 are not part of this branch ancestry. #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` closes runtime final-column parity and `atttypmod` authority on top of #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65`; both remain Draft candidate evidence until normal protected integration. Final documentation convergence must preserve both Result Application and lifecycle/outbox evidence after their source lineages legitimately integrate. ## Current product / technical gaps -1. **Dependency-root integration:** #233 remains outside protected `main` at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. Repository-owned deterministic/security lanes are not sufficient to authorize it while the central required-workflow and independent-review path is unresolved. Protected `ContextualWisdomLab/.github/main` is exact `78393ea901efc0d57b35dd1e383e473425b7c1da`. `.github#2079` has repaired the finding/probe relation source defect at exact `9dccfaa0776950498e557390a2fa8d6c34e0baf4`, but it is now **Draft** because Required OpenCode Review `34757059796` failed deterministic `coverage-evidence` at touched-callable docstring coverage **76.47% (13/17; threshold 80%)**. Fresh diff inspection confirms the missing documentation is confined to four nested fixture methods in `tests/test_noema_review_gate.py`: `Response.__enter__`, `Response.__exit__`, `Response.read`, and `Opener.open`. The minimum causal repair is meaningful docstrings on those four methods followed by fresh exact-head evidence; lowering the threshold, manufacturing a wake commit, or retrying the model path around the deterministic RED is not valid. The branch also retains stale base metadata `64f483db9d052322c65bcdf1675d66138156f306`, so source GREEN must be followed by ordinary/non-force reconciliation to current protected central main and fresh current-base gates. Scheduler/RCA owner `.github#2170@d3f1d0264912e74b897fdf2a0a6085100de4e40a` is directly based on `78393ea...` and has repaired the control-plane blind spot that previously excluded `Required OpenCode Review / coverage-evidence` from bounded RCA while continuing to exclude `opencode-review` and other/unknown OpenCode-family workflows. Its SAST, Security Scan, and Agent Review Runtime Quality lanes are terminal GREEN, while CodeQL remains queued and Python Security is non-terminal; its evidence does not transfer to #2079. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` likewise retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306`; it must reconcile to current protected central authority rather than receive a leaf-side wake commit. Its historical Noema run `34739350198` exposed a separate serving defect: five routes were preflight-ready, but a timeout on the selected route ended the virtual `orchestrator/free` request without trying other ready candidates. That behavior now has an implementation owner in `contextual-orchestrator#1176@a9cb8c6749008904815c663ebd8f8fff7099d6ae`, based directly on protected CO `main@767e67fbc6b881a452761f32abb69b9971b9b03b`: virtual selectors advance across ambiguous transport timeouts while explicit concrete-model requests remain single-shot/fail-closed. Exact-head Security Scan, Semgrep, and Security and Quality are GREEN; CodeQL PR `34759495194` is terminal FAILURE in the central compatibility-enforcement family, so no CO source/SARIF defect is inferred from that gate alone and #1176 remains neither protected nor released authority. `.github#2140` remains useful architectural/progress-boundary work, but it is no longer the only implementation path for this multi-ready timeout case. Probe/catalog/free-tier capacity and permanent-dead-slot budget remain separate owner work under `.github#1948`. The independent CodeQL deployment-order lane is also terminally characterized: `.github#2106@db34e6b9d739c5ef228bacdc2efaa5f3a9238356` is Ready/open/mergeable directly on current protected central `main@78393ea...`, but CodeQL PR `34761450697` is terminal FAILURE. Language detection succeeded; both compatibility receivers read the current-head dispatch verdict and failed only at `Release runner or enforce current-head CodeQL verdict`; only after those terminal receiver failures did `Dispatch current-head CodeQL scan` succeed. This is producer-after-terminal-consumer/bootstrap evidence rather than a source/SARIF finding. Repair therefore remains `#2106 -> normal protected integration -> Draft #2040@85522306949bada2b5939608dc911f6374125f1b ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence and unchanged external canary`. No pg-side copied workflow, source-neutral wake commit, PYTHONPATH workaround, synthetic status, provider/model hard-code, paid fallback, manual rerun loop, or protection bypass is valid evidence. -2. **Lifecycle/outbox convergence:** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. -3. **Diagnostic privacy and warning hygiene:** protected `main` still copies caller-controlled values into package-owned exception authority. `ValidationError` renders and retains rejected `value` by default (#132), while `TokenLimitExceededError` copies raw `batch_id` into both exception text and structured `details` (#304). The previous source-writer overlap is no longer current: Draft #202 is exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33`, ordinary/non-force stacked directly on #323 exact `34858ef2f96307273853901bef932ec2958e4931`, and its effective production delta is confined to `pg_llm_batch/exceptions.py` plus privacy-focused tests rather than stale `orchestrator.py` ownership. #202 exact-head CI `34756635313` and Release Acceptance `34756635333` are branch-local GREEN. Draft #344 is the serialized #304 child of #202 at exact `03be5eaca49c7c76922df8545dcc4f72842567e8`; it keeps `batch_id` in the constructor for compatibility but neither truth-tests, renders, hashes, nor retains it, while preserving exact `current_tokens`, `limit_tokens`, `excess_tokens`, and `TOKEN_LIMIT_EXCEEDED`. Its test contract also rejects behavior-bearing identifier authority. Exact-head CI `34757663693` and Release Acceptance `34757663694` are GREEN with 100% public docstrings and 100.00% production statement/branch coverage (`4729` statements, `1348` branches, zero misses/partials). This is not shipped truth: #202/#344 remain Draft descendants outside protected main. Their Python 3.14 quality runs also expose five inherited warnings that are not waived: four synthetic schema-close finalizer warnings are canonically repaired by Draft #251, and the independent compose/runpy RuntimeWarning by Draft #252. #252's exact GREEN proves the combined `#251 -> #252` warning lineage reaches zero warnings. Privacy and warning lanes must converge through their existing owners after #233 rather than copying sibling fixes or suppressing diagnostics. -4. **Buyer latency envelope:** issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim; security/admission work may not be excluded merely to meet it. -5. **Immutable release:** exact-head CI and reproducible build checks are necessary but are not an immutable release. Fresh GitHub Release reads still return zero releases for both `pg-llm-batch` and `contextual-orchestrator`. Protected CO `main` is exact `767e67fbc6b881a452761f32abb69b9971b9b03b`, but packaging prerequisite #995 remains exact `29b7f5457ee6a9c2a1f25f1e564f798d419bacc9` on stale base `012beaacd0631f8cd3391c77744eeb626269b5de`, and canonical release owner #1030 remains Draft exact `b51009c8b5b6c9e79672e412a87e5b4609f42173` on much older base `414f22973658c4ddc3d4320fcf7acd9b4e8ba991`. Central `.github#2163` consuming protected CO source `767e67fb...` fixes the implicit-timeout incident but does not convert that source SHA into a released API/client/schema contract. #995 and #1030 must reconcile through ordinary protected ancestry and the release lane must actually publish version/CHANGELOG/tag/package, exact-commit SBOM, provenance, reproducibility and rollback evidence before central or pg consumers treat CO identity as released authority. -6. **Consumer integration:** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. The normal dependency direction is owner RED → causal repair → exact-head GREEN → protected integration → immutable release → consumer pin/canary, not a leaf-side substitute for an unreleased foundation contract. +1. **Dependency-root and central review integration.** pg protected `main` remains `5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c`; #233 remains outside it at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. #233 is Ready/open/mergeable, changes only `tests/test_postgres_recovery_evidence_registry.py`, and has no production-source delta, but repository-local GREEN cannot substitute for the live central required-workflow path and qualifying independent approval. + + Protected `ContextualWisdomLab/.github/main` is now exact `828eaaefb0cc97bba4da63eb9270447476d26710`. Noema owner `.github#2079` has moved from the former 76.47% docstring RED to exact `6d7e833224e06b4316df3d6bbdfcb4658e151956`, directly based on that protected tip. The finding↔confirmed-probe relation repair is retained, the changed-location truncation regression is isolated in its own test module, and the four previously undocumented nested fixture methods now have behavior-specific docstrings. #2079 is Ready/open/mergeable, but its fresh post-Ready CodeQL, Semgrep, Security, Python Security, `noema-review`, and admission generation is still queued/non-terminal. Cancelled pre-Ready runs are not failures and predecessor evidence does not transfer. The valid state is therefore **source repaired / current-main reconciled / exact-head acceptance pending**, not GREEN or merge-authorized. + + Scheduler/RCA owner `.github#2170` has also advanced. Exact `ae0f2f57f1d2abda7bb2e7ac9ce3bf8f1cac6f39` is directly based on protected central `main@828eaaef...`. Besides admitting only the exact `(Required OpenCode Review, coverage-evidence)` tuple into bounded RCA, it repairs a hosted full-suite dependency-closure failure: `review_repair_suite` executes the unscoped full pytest gate, which imports the Noema document path and therefore also requires the hashed `defusedxml` dependency lock. The source repair is present, but fresh exact-head CodeQL, Security, Python Security, Runtime Quality, and Semgrep runs are queued. No manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. + + `.github#2094@5f90b418187482e7eee1d295d09145e899853925` retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306` and is currently non-mergeable. It must reconcile normally to current protected central authority rather than receive a pg-side wake commit. + + The independent CodeQL deployment-order owner `.github#2106` is now exact `1ba96e4ddf6a800435651ec1c49acff533242fd9`, Ready/open/mergeable, directly based on protected central `main@828eaaef...`. Its PR body contains older historical head snapshots and must not be used as exact-current authority. On the exact current head, Runtime Quality is terminal SUCCESS while CodeQL, Security, Semgrep, and Python Security are freshly queued. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. + +2. **Lifecycle/outbox convergence.** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. + +3. **Diagnostic privacy and warning hygiene.** Protected `main` still contains diagnostic surfaces whose privacy repairs are unshipped branch candidates. Draft #323 exact `34858ef2f96307273853901bef932ec2958e4931` is the PostgreSQL-driver foundation; Draft #202 exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33` is its serialized `ValidationError` privacy child; Draft #344 exact `03be5eaca49c7c76922df8545dcc4f72842567e8` is the token-limit identity-privacy child; TLS child #342 exact `d59df8ff14f8d82ac01f866cb38889407634cc46` remains stacked on the driver foundation. Their branch-local GREEN does not make them shipped truth. Warning-hygiene children remain correctly serialized behind #233: #251 exact `07057cf916e1105a1ddd262d48327a4d3f01500e` owns the schema-finalizer warning repair and #252 exact `e3668344af050672387ca58e59ea24d23d98e51b` owns the compose/runpy RuntimeWarning repair. Warnings and deprecations are root-cause findings, not suppressible noise. + +4. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 currently own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. + +5. **Provider-neutral review transport and immutable CO release.** Protected `contextual-orchestrator/main` remains exact `767e67fbc6b881a452761f32abb69b9971b9b03b`, where the implicit model request timeout was removed. Historical multi-ready Noema timeouts now have a source owner in `contextual-orchestrator#1176@a9cb8c6749008904815c663ebd8f8fff7099d6ae`, directly based on that protected tip: virtual selectors may advance across ambiguous transport timeouts while explicit concrete-model requests remain single-shot/fail-closed. #1176 is Ready/open/mergeable but remains unintegrated and unreleased. + + Packaging prerequisite #995 remains exact `29b7f5457ee6a9c2a1f25f1e564f798d419bacc9`, Ready but non-mergeable on stale base `012beaacd0631f8cd3391c77744eeb626269b5de`. Canonical immutable-release owner #1030 has advanced to exact `c525ae41a7bb6b6816551094742ea0ef96b48544`, but remains Draft/non-mergeable on stale base `414f22973658c4ddc3d4320fcf7acd9b4e8ba991`; historical head values in its body are not current authority. Fresh GitHub Release reads still return zero releases for both `contextual-orchestrator` and `pg-llm-batch`. A protected source SHA, sidecar pin, branch-local GREEN, or mergeable PR is therefore not a released API/client/schema contract. + + The required order is owner RED -> causal source repair -> exact-head GREEN -> protected integration -> version/CHANGELOG/tag/package -> exact-commit SBOM/provenance/reproducibility/rollback -> immutable Release -> thin consumer pin/canary. Central Actions model-backed workflows may consume only the released CO boundary through a gateway token and `orchestrator/free`; provider/model/group secrets or paid fallback remain CO-owned and must not be hard-coded in pg or central leaf workflows. + +6. **Consumer integration.** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. pg owns its PostgreSQL/domain truth; foundation repositories contribute only versioned released contracts and ACLs. ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. +Long-running LLM/provider/model computation must occur outside an explicit PostgreSQL transaction and without holding avoidable database locks. A transaction may protect the minimal aggregate state transition before or after external work; it must not remain idle while waiting for remote inference or CPU/GPU computation. + ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. This baseline records the branch-local Result Application truth and explicitly marks unintegrated sibling/security, diagnostic-privacy, warning-hygiene, performance, approval, central-workflow and release work as gaps. It does not transfer predecessor checks, claim an unmerged sibling's runtime guarantees, treat a green development head as a published release, or promote a central prerequisite's current branch state into pg product behavior. +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local, or mechanically mergeable evidence is not promoted to protected or released truth. This baseline records Result Application branch truth and explicitly marks unintegrated lifecycle/security, diagnostic-privacy, warning-hygiene, performance, approval, central-workflow, provider-routing, and release work as gaps. \ No newline at end of file From 14a5fb1ad911fb7852b80ef03b2c5978894ca18b Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 14 Sep 2026 06:06:36 +0900 Subject: [PATCH 27/57] docs(gaps): refresh central gates and database wait seam --- docs/product-technical-gap-baseline.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 27669919e..281a49234 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -34,27 +34,29 @@ The active lifecycle/outbox security work in sibling PR #319 and its direct runt 1. **Dependency-root and central review integration.** pg protected `main` remains `5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c`; #233 remains outside it at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. #233 is Ready/open/mergeable, changes only `tests/test_postgres_recovery_evidence_registry.py`, and has no production-source delta, but repository-local GREEN cannot substitute for the live central required-workflow path and qualifying independent approval. - Protected `ContextualWisdomLab/.github/main` is now exact `828eaaefb0cc97bba4da63eb9270447476d26710`. Noema owner `.github#2079` has moved from the former 76.47% docstring RED to exact `6d7e833224e06b4316df3d6bbdfcb4658e151956`, directly based on that protected tip. The finding↔confirmed-probe relation repair is retained, the changed-location truncation regression is isolated in its own test module, and the four previously undocumented nested fixture methods now have behavior-specific docstrings. #2079 is Ready/open/mergeable, but its fresh post-Ready CodeQL, Semgrep, Security, Python Security, `noema-review`, and admission generation is still queued/non-terminal. Cancelled pre-Ready runs are not failures and predecessor evidence does not transfer. The valid state is therefore **source repaired / current-main reconciled / exact-head acceptance pending**, not GREEN or merge-authorized. + Protected `ContextualWisdomLab/.github/main` is exact `828eaaefb0cc97bba4da63eb9270447476d26710`. Noema owner `.github#2079` is exact `6d7e833224e06b4316df3d6bbdfcb4658e151956`, directly based on that protected tip. The finding↔confirmed-probe relation repair is retained, the changed-location truncation regression is isolated in its own test module, and the former four undocumented fixture methods now have behavior-specific docstrings. SAST `34773503968`, Security Scan `34773503951`, and Python Security `34773503958` are terminal SUCCESS. CodeQL run `34773503966` remains non-terminal: its first-attempt actions/python compatibility jobs returned the protected v1 protocol's pending verdict and failed to release their runners, while the run-wide `Dispatch current-head CodeQL scan` coordinator is still queued. Those intermediate shard failures are not a completed source/SARIF RED until the coordinator/receipt/rerun protocol settles. Required OpenCode `coverage-evidence`, `coverage-source-tree`, and `opencode-review` are also queued. The valid state is **source repaired / current-main reconciled / exact-head acceptance pending**, not GREEN or merge-authorized. - Scheduler/RCA owner `.github#2170` has also advanced. Exact `ae0f2f57f1d2abda7bb2e7ac9ce3bf8f1cac6f39` is directly based on protected central `main@828eaaef...`. Besides admitting only the exact `(Required OpenCode Review, coverage-evidence)` tuple into bounded RCA, it repairs a hosted full-suite dependency-closure failure: `review_repair_suite` executes the unscoped full pytest gate, which imports the Noema document path and therefore also requires the hashed `defusedxml` dependency lock. The source repair is present, but fresh exact-head CodeQL, Security, Python Security, Runtime Quality, and Semgrep runs are queued. No manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. + Scheduler/RCA owner `.github#2170@ae0f2f57f1d2abda7bb2e7ac9ce3bf8f1cac6f39` is also directly based on protected central main. Besides admitting only the exact `(Required OpenCode Review, coverage-evidence)` tuple into bounded RCA, it repairs a hosted full-suite dependency-closure failure: `review_repair_suite` executes the unscoped full pytest gate, which imports the Noema document path and therefore also requires the hashed `defusedxml` dependency lock. Agent Review Runtime Quality CI `34775874685` is terminal SUCCESS on the repaired exact head; CodeQL, Security, Python Security, and Semgrep remain queued. No manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306` and is currently non-mergeable. It must reconcile normally to current protected central authority rather than receive a pg-side wake commit. - The independent CodeQL deployment-order owner `.github#2106` is now exact `1ba96e4ddf6a800435651ec1c49acff533242fd9`, Ready/open/mergeable, directly based on protected central `main@828eaaef...`. Its PR body contains older historical head snapshots and must not be used as exact-current authority. On the exact current head, Runtime Quality is terminal SUCCESS while CodeQL, Security, Semgrep, and Python Security are freshly queued. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. + The independent CodeQL deployment-order owner `.github#2106` is exact `1ba96e4ddf6a800435651ec1c49acff533242fd9`, Ready/open/mergeable, directly based on protected central main. Runtime Quality, Security, Python Security, and Semgrep are terminal SUCCESS. CodeQL run `34773233399` remains non-terminal under the same protected-v1 fail-pending-then-dispatch/rerun protocol: language detection succeeded, first-attempt actions/python compatibility jobs failed with a pending verdict, and the run-wide dispatch coordinator is still queued. This is acceptance-pending rather than terminal GREEN, but the first-attempt failures must not be mislabeled as a completed CodeQL source/SARIF defect before the coordinator settles. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. 2. **Lifecycle/outbox convergence.** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. -3. **Diagnostic privacy and warning hygiene.** Protected `main` still contains diagnostic surfaces whose privacy repairs are unshipped branch candidates. Draft #323 exact `34858ef2f96307273853901bef932ec2958e4931` is the PostgreSQL-driver foundation; Draft #202 exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33` is its serialized `ValidationError` privacy child; Draft #344 exact `03be5eaca49c7c76922df8545dcc4f72842567e8` is the token-limit identity-privacy child; TLS child #342 exact `d59df8ff14f8d82ac01f866cb38889407634cc46` remains stacked on the driver foundation. Their branch-local GREEN does not make them shipped truth. Warning-hygiene children remain correctly serialized behind #233: #251 exact `07057cf916e1105a1ddd262d48327a4d3f01500e` owns the schema-finalizer warning repair and #252 exact `e3668344af050672387ca58e59ea24d23d98e51b` owns the compose/runpy RuntimeWarning repair. Warnings and deprecations are root-cause findings, not suppressible noise. +3. **Database wait envelope and transaction recovery.** Issue #122 remains open because protected product code does not yet enforce one package-wide policy for package-owned connection acquisition, statement duration, and lock wait. Draft driver foundation #323 exact `34858ef2f96307273853901bef932ec2958e4931` already provides the canonical post-integration acquisition primitive, `PostgresDriverPort.connect(..., connect_timeout_seconds=...)`. Its admitted pg8000 adapter validates a positive finite timeout and forwards it as the DB-API `timeout=` keyword after parsing the existing selector; it does not forward or rewrite the original credential-bearing DSN merely to inject the timeout. Therefore #122 must not introduce a competing timeout API. After #323 integrates, the remaining causal work is an operation-class call-site budget, package-owned PostgreSQL statement/lock budgets, cancellation→rollback/recovery evidence, and real PostgreSQL proof that LLM/provider/network or long CPU/GPU work does not retain an avoidable transaction or lock. Caller-owned/injected transaction authority, including Result Application's atomic result/checkpoint seam, remains outside package-side silent reconfiguration. -4. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 currently own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. +4. **Diagnostic privacy and warning hygiene.** Protected `main` still contains diagnostic surfaces whose privacy repairs are unshipped branch candidates. Draft #323 exact `34858ef2f96307273853901bef932ec2958e4931` is the PostgreSQL-driver foundation; Draft #202 exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33` is its serialized `ValidationError` privacy child; Draft #344 exact `03be5eaca49c7c76922df8545dcc4f72842567e8` is the token-limit identity-privacy child; TLS child #342 exact `d59df8ff14f8d82ac01f866cb38889407634cc46` remains stacked on the driver foundation. Their branch-local GREEN does not make them shipped truth. Warning-hygiene children remain correctly serialized behind #233: #251 exact `07057cf916e1105a1ddd262d48327a4d3f01500e` owns the schema-finalizer warning repair and #252 exact `e3668344af050672387ca58e59ea24d23d98e51b` owns the compose/runpy RuntimeWarning repair. Warnings and deprecations are root-cause findings, not suppressible noise. -5. **Provider-neutral review transport and immutable CO release.** Protected `contextual-orchestrator/main` remains exact `767e67fbc6b881a452761f32abb69b9971b9b03b`, where the implicit model request timeout was removed. Historical multi-ready Noema timeouts now have a source owner in `contextual-orchestrator#1176@a9cb8c6749008904815c663ebd8f8fff7099d6ae`, directly based on that protected tip: virtual selectors may advance across ambiguous transport timeouts while explicit concrete-model requests remain single-shot/fail-closed. #1176 is Ready/open/mergeable but remains unintegrated and unreleased. +5. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 currently own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. - Packaging prerequisite #995 remains exact `29b7f5457ee6a9c2a1f25f1e564f798d419bacc9`, Ready but non-mergeable on stale base `012beaacd0631f8cd3391c77744eeb626269b5de`. Canonical immutable-release owner #1030 has advanced to exact `c525ae41a7bb6b6816551094742ea0ef96b48544`, but remains Draft/non-mergeable on stale base `414f22973658c4ddc3d4320fcf7acd9b4e8ba991`; historical head values in its body are not current authority. Fresh GitHub Release reads still return zero releases for both `contextual-orchestrator` and `pg-llm-batch`. A protected source SHA, sidecar pin, branch-local GREEN, or mergeable PR is therefore not a released API/client/schema contract. +6. **Provider-neutral review transport and immutable CO release.** Protected `contextual-orchestrator/main` remains exact `767e67fbc6b881a452761f32abb69b9971b9b03b`, where the implicit model request timeout was removed. Historical multi-ready Noema timeouts have a source owner in `contextual-orchestrator#1176@a9cb8c6749008904815c663ebd8f8fff7099d6ae`, directly based on that protected tip: virtual selectors may advance across ambiguous transport timeouts while explicit concrete-model requests remain single-shot/fail-closed. #1176 is Ready/open/mergeable but remains unintegrated and unreleased. + + Packaging prerequisite #995 remains exact `29b7f5457ee6a9c2a1f25f1e564f798d419bacc9`, Ready but non-mergeable on stale base `012beaacd0631f8cd3391c77744eeb626269b5de`. Canonical immutable-release owner #1030 is exact `c525ae41a7bb6b6816551094742ea0ef96b48544`, but remains Draft/non-mergeable on stale base `414f22973658c4ddc3d4320fcf7acd9b4e8ba991`; historical head values in its body are not current authority. A protected source SHA, sidecar pin, branch-local GREEN, or mergeable PR is not a released API/client/schema contract. The required order is owner RED -> causal source repair -> exact-head GREEN -> protected integration -> version/CHANGELOG/tag/package -> exact-commit SBOM/provenance/reproducibility/rollback -> immutable Release -> thin consumer pin/canary. Central Actions model-backed workflows may consume only the released CO boundary through a gateway token and `orchestrator/free`; provider/model/group secrets or paid fallback remain CO-owned and must not be hard-coded in pg or central leaf workflows. -6. **Consumer integration.** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. pg owns its PostgreSQL/domain truth; foundation repositories contribute only versioned released contracts and ACLs. +7. **Consumer integration.** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. pg owns its PostgreSQL/domain truth; foundation repositories contribute only versioned released contracts and ACLs. ## Security / operability baseline @@ -64,4 +66,4 @@ Long-running LLM/provider/model computation must occur outside an explicit Postg ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local, or mechanically mergeable evidence is not promoted to protected or released truth. This baseline records Result Application branch truth and explicitly marks unintegrated lifecycle/security, diagnostic-privacy, warning-hygiene, performance, approval, central-workflow, provider-routing, and release work as gaps. \ No newline at end of file +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local, or mechanically mergeable evidence is not promoted to protected or released truth. This baseline records Result Application branch truth and explicitly marks unintegrated lifecycle/security, database-wait/recovery, diagnostic-privacy, warning-hygiene, performance, approval, central-workflow, provider-routing, and release work as gaps. \ No newline at end of file From 509f0b888f0ddcfc0320b2b7edf5e5a9474783fa Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 14 Sep 2026 08:05:36 +0900 Subject: [PATCH 28/57] docs: stabilize central acceptance authority --- docs/product-technical-gap-baseline.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 281a49234..8003bf2e6 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -30,17 +30,19 @@ PR #324 on `fix/result-application-semantic-identifiers` is the documentation-on The active lifecycle/outbox security work in sibling PR #319 and its direct runtime-column authority child #336 are not part of this branch ancestry. #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` closes runtime final-column parity and `atttypmod` authority on top of #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65`; both remain Draft candidate evidence until normal protected integration. Final documentation convergence must preserve both Result Application and lifecycle/outbox evidence after their source lineages legitimately integrate. +Transient hosted-run state belongs in the live integration ledger (#244) and the owning central PR, not in this baseline. This document records durable ownership, protocol state, integration order, and product gaps so a queued runner or a later receipt does not immediately stale the product contract. + ## Current product / technical gaps 1. **Dependency-root and central review integration.** pg protected `main` remains `5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c`; #233 remains outside it at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. #233 is Ready/open/mergeable, changes only `tests/test_postgres_recovery_evidence_registry.py`, and has no production-source delta, but repository-local GREEN cannot substitute for the live central required-workflow path and qualifying independent approval. - Protected `ContextualWisdomLab/.github/main` is exact `828eaaefb0cc97bba4da63eb9270447476d26710`. Noema owner `.github#2079` is exact `6d7e833224e06b4316df3d6bbdfcb4658e151956`, directly based on that protected tip. The finding↔confirmed-probe relation repair is retained, the changed-location truncation regression is isolated in its own test module, and the former four undocumented fixture methods now have behavior-specific docstrings. SAST `34773503968`, Security Scan `34773503951`, and Python Security `34773503958` are terminal SUCCESS. CodeQL run `34773503966` remains non-terminal: its first-attempt actions/python compatibility jobs returned the protected v1 protocol's pending verdict and failed to release their runners, while the run-wide `Dispatch current-head CodeQL scan` coordinator is still queued. Those intermediate shard failures are not a completed source/SARIF RED until the coordinator/receipt/rerun protocol settles. Required OpenCode `coverage-evidence`, `coverage-source-tree`, and `opencode-review` are also queued. The valid state is **source repaired / current-main reconciled / exact-head acceptance pending**, not GREEN or merge-authorized. + Protected `ContextualWisdomLab/.github/main` is exact `828eaaefb0cc97bba4da63eb9270447476d26710`. Noema owner `.github#2079` is exact `6d7e833224e06b4316df3d6bbdfcb4658e151956`, directly based on that protected tip. The finding↔confirmed-probe relation repair is retained, the changed-location truncation regression is isolated in its own test module, and the former four undocumented fixture methods now have behavior-specific docstrings. Repository security/static-analysis lanes other than CodeQL have terminal exact-head success. The current CodeQL required run has reached a first-pass terminal failure under the protected dispatch/receipt protocol; that first pass is not by itself a source/SARIF verdict because protected-handler settlement is a separate protocol phase. The durable classification remains **source repaired / current-main reconciled / exact-head acceptance pending** until the live central owner records terminal settlement and required review evidence. No predecessor GREEN, manual rerun, no-op wake commit, or threshold weakening may substitute for that evidence. - Scheduler/RCA owner `.github#2170@ae0f2f57f1d2abda7bb2e7ac9ce3bf8f1cac6f39` is also directly based on protected central main. Besides admitting only the exact `(Required OpenCode Review, coverage-evidence)` tuple into bounded RCA, it repairs a hosted full-suite dependency-closure failure: `review_repair_suite` executes the unscoped full pytest gate, which imports the Noema document path and therefore also requires the hashed `defusedxml` dependency lock. Agent Review Runtime Quality CI `34775874685` is terminal SUCCESS on the repaired exact head; CodeQL, Security, Python Security, and Semgrep remain queued. No manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. + Scheduler/RCA owner `.github#2170@ae0f2f57f1d2abda7bb2e7ac9ce3bf8f1cac6f39` is also directly based on protected central main. Besides admitting only the exact `(Required OpenCode Review, coverage-evidence)` tuple into bounded RCA, it repairs a hosted full-suite dependency-closure failure: `review_repair_suite` executes the unscoped full pytest gate, which imports the Noema document path and therefore also requires the hashed `defusedxml` dependency lock. Agent Review Runtime Quality, Security Scan, Python Security, and Semgrep are terminal SUCCESS on the repaired exact head; CodeQL remains acceptance-pending. No manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306` and is currently non-mergeable. It must reconcile normally to current protected central authority rather than receive a pg-side wake commit. - The independent CodeQL deployment-order owner `.github#2106` is exact `1ba96e4ddf6a800435651ec1c49acff533242fd9`, Ready/open/mergeable, directly based on protected central main. Runtime Quality, Security, Python Security, and Semgrep are terminal SUCCESS. CodeQL run `34773233399` remains non-terminal under the same protected-v1 fail-pending-then-dispatch/rerun protocol: language detection succeeded, first-attempt actions/python compatibility jobs failed with a pending verdict, and the run-wide dispatch coordinator is still queued. This is acceptance-pending rather than terminal GREEN, but the first-attempt failures must not be mislabeled as a completed CodeQL source/SARIF defect before the coordinator settles. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. + The independent CodeQL deployment-order owner `.github#2106` is exact `1ba96e4ddf6a800435651ec1c49acff533242fd9`, Ready/open/mergeable, directly based on protected central main. Runtime Quality, Security, Python Security, and Semgrep are terminal SUCCESS. Its required CodeQL first pass has completed FAILURE after the compatibility shards observed the protected-v1 pending verdict and the run-wide dispatch step completed. An exact matching protected-handler dispatch exists for the current PR/base/required-run tuple but is still waiting for hosted execution with no runner assigned in the latest sweep. Therefore the correct state is **SOURCE_REPAIRED / PROTECTED_HANDLER_ACCEPTANCE_PENDING**, not a completed source/SARIF RED and not GREEN. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. 2. **Lifecycle/outbox convergence.** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. @@ -66,4 +68,4 @@ Long-running LLM/provider/model computation must occur outside an explicit Postg ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local, or mechanically mergeable evidence is not promoted to protected or released truth. This baseline records Result Application branch truth and explicitly marks unintegrated lifecycle/security, database-wait/recovery, diagnostic-privacy, warning-hygiene, performance, approval, central-workflow, provider-routing, and release work as gaps. \ No newline at end of file +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local, or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. \ No newline at end of file From c6205eee220a939252e2a44c87b9c319a6e0ce92 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 14 Sep 2026 09:08:58 +0900 Subject: [PATCH 29/57] docs(gaps): reconcile central prerequisite heads --- docs/product-technical-gap-baseline.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 8003bf2e6..c3e0fdb8c 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,13 +36,13 @@ Transient hosted-run state belongs in the live integration ledger (#244) and the 1. **Dependency-root and central review integration.** pg protected `main` remains `5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c`; #233 remains outside it at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. #233 is Ready/open/mergeable, changes only `tests/test_postgres_recovery_evidence_registry.py`, and has no production-source delta, but repository-local GREEN cannot substitute for the live central required-workflow path and qualifying independent approval. - Protected `ContextualWisdomLab/.github/main` is exact `828eaaefb0cc97bba4da63eb9270447476d26710`. Noema owner `.github#2079` is exact `6d7e833224e06b4316df3d6bbdfcb4658e151956`, directly based on that protected tip. The finding↔confirmed-probe relation repair is retained, the changed-location truncation regression is isolated in its own test module, and the former four undocumented fixture methods now have behavior-specific docstrings. Repository security/static-analysis lanes other than CodeQL have terminal exact-head success. The current CodeQL required run has reached a first-pass terminal failure under the protected dispatch/receipt protocol; that first pass is not by itself a source/SARIF verdict because protected-handler settlement is a separate protocol phase. The durable classification remains **source repaired / current-main reconciled / exact-head acceptance pending** until the live central owner records terminal settlement and required review evidence. No predecessor GREEN, manual rerun, no-op wake commit, or threshold weakening may substitute for that evidence. + Protected `ContextualWisdomLab/.github/main` is exact `ebc69a4016f7668beaef5e3b592d378f22ada684`. Noema owner `.github#2079` is exact `e7c5044c4a6228850829660e32b1bed342cc5cb3`, directly based on that protected tip after ordinary non-force reconciliation. The finding↔confirmed-probe relation repair, dedicated changed-location truncation regression, and behavior-specific fixture docstrings remain intact. Because the head moved to absorb the protected OpenCode `python/` source-root repair, predecessor workflow receipts are historical; the durable classification remains **source repaired / current-main reconciled / exact-head acceptance pending** until the new exact-head required workflows and independent review settle. No predecessor GREEN, manual rerun, no-op wake commit, or threshold weakening may substitute for that evidence. - Scheduler/RCA owner `.github#2170@ae0f2f57f1d2abda7bb2e7ac9ce3bf8f1cac6f39` is also directly based on protected central main. Besides admitting only the exact `(Required OpenCode Review, coverage-evidence)` tuple into bounded RCA, it repairs a hosted full-suite dependency-closure failure: `review_repair_suite` executes the unscoped full pytest gate, which imports the Noema document path and therefore also requires the hashed `defusedxml` dependency lock. Agent Review Runtime Quality, Security Scan, Python Security, and Semgrep are terminal SUCCESS on the repaired exact head; CodeQL remains acceptance-pending. No manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. + Scheduler/RCA owner `.github#2170@c741b608322208b8bc222792ceb3b6c63207e157` is also directly based on protected central main after ordinary non-force reconciliation. It retains the exact `(Required OpenCode Review, coverage-evidence)` admission repair and the hosted full-suite `defusedxml` dependency-closure repair. The protected-main advance invalidates predecessor hosted receipts as merge authority, so the reconciled exact head must reacquire its own workflows and qualifying review; no manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306` and is currently non-mergeable. It must reconcile normally to current protected central authority rather than receive a pg-side wake commit. - The independent CodeQL deployment-order owner `.github#2106` is exact `1ba96e4ddf6a800435651ec1c49acff533242fd9`, Ready/open/mergeable, directly based on protected central main. Runtime Quality, Security, Python Security, and Semgrep are terminal SUCCESS. Its required CodeQL first pass has completed FAILURE after the compatibility shards observed the protected-v1 pending verdict and the run-wide dispatch step completed. An exact matching protected-handler dispatch exists for the current PR/base/required-run tuple but is still waiting for hosted execution with no runner assigned in the latest sweep. Therefore the correct state is **SOURCE_REPAIRED / PROTECTED_HANDLER_ACCEPTANCE_PENDING**, not a completed source/SARIF RED and not GREEN. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. + The independent CodeQL deployment-order owner `.github#2106` is exact `4288590362282074d55ef874291ffc2ba884e93d`, Ready/open/mergeable, and directly based on protected central `main@ebc69a4016f7668beaef5e3b592d378f22ada684`. Ordinary reverse PR #2185 performed the semantic non-force merge of the protected advance, preserving both #2106's seven-path v1/v2 settlement delta and the protected OpenCode `python/` source-root changelog/product-gap evidence. The old protected-handler dispatch bound to predecessor tuple `#2106@1ba96e.../828eaa...` is historical and cannot authorize this head. Current classification is **SOURCE_REPAIRED / CURRENT_MAIN_RECONCILED / EXACT_HEAD_ACCEPTANCE_PENDING**. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. 2. **Lifecycle/outbox convergence.** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. From ca13a28ed1cfb61f1f12fee98a95d7943c697406 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 14 Sep 2026 10:09:41 +0900 Subject: [PATCH 30/57] docs(gap): reconcile central prerequisite heads --- docs/product-technical-gap-baseline.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index c3e0fdb8c..fa93b678b 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,13 +36,13 @@ Transient hosted-run state belongs in the live integration ledger (#244) and the 1. **Dependency-root and central review integration.** pg protected `main` remains `5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c`; #233 remains outside it at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. #233 is Ready/open/mergeable, changes only `tests/test_postgres_recovery_evidence_registry.py`, and has no production-source delta, but repository-local GREEN cannot substitute for the live central required-workflow path and qualifying independent approval. - Protected `ContextualWisdomLab/.github/main` is exact `ebc69a4016f7668beaef5e3b592d378f22ada684`. Noema owner `.github#2079` is exact `e7c5044c4a6228850829660e32b1bed342cc5cb3`, directly based on that protected tip after ordinary non-force reconciliation. The finding↔confirmed-probe relation repair, dedicated changed-location truncation regression, and behavior-specific fixture docstrings remain intact. Because the head moved to absorb the protected OpenCode `python/` source-root repair, predecessor workflow receipts are historical; the durable classification remains **source repaired / current-main reconciled / exact-head acceptance pending** until the new exact-head required workflows and independent review settle. No predecessor GREEN, manual rerun, no-op wake commit, or threshold weakening may substitute for that evidence. + Protected `ContextualWisdomLab/.github/main` is exact `7f07029381a9ca770d0a68b7f3938dd652799d4d` after the protected Semgrep runner-fold and intervening security/tooling advances. Noema owner `.github#2079` is exact `2d27e0c13f9b118ca844f5299b0fcdde420fa66b`, directly based on that protected tip after ordinary non-force reconciliation through reverse PR #2188. The finding↔confirmed-probe relation repair, dedicated changed-location truncation regression, and behavior-specific fixture docstrings remain intact. Because the head moved to absorb the protected central advances, predecessor workflow receipts are historical; the durable classification remains **source repaired / current-main reconciled / exact-head acceptance pending** until the new exact-head required workflows and independent review settle. No predecessor GREEN, manual rerun, no-op wake commit, or threshold weakening may substitute for that evidence. - Scheduler/RCA owner `.github#2170@c741b608322208b8bc222792ceb3b6c63207e157` is also directly based on protected central main after ordinary non-force reconciliation. It retains the exact `(Required OpenCode Review, coverage-evidence)` admission repair and the hosted full-suite `defusedxml` dependency-closure repair. The protected-main advance invalidates predecessor hosted receipts as merge authority, so the reconciled exact head must reacquire its own workflows and qualifying review; no manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. + Scheduler/RCA owner `.github#2170@d493cc4c53d0b77d67ef4af13005dcda8fb33c7f` is also directly based on protected central main after ordinary non-force reconciliation through reverse PR #2189. It retains the exact `(Required OpenCode Review, coverage-evidence)` admission repair and the hosted full-suite `defusedxml` dependency-closure repair. The protected-main advance invalidates predecessor hosted receipts as merge authority, so the reconciled exact head must reacquire its own workflows and qualifying review; no manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. `.github#2094@5f90b418187482e7eee1d295d09145e899853925` retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306` and is currently non-mergeable. It must reconcile normally to current protected central authority rather than receive a pg-side wake commit. - The independent CodeQL deployment-order owner `.github#2106` is exact `4288590362282074d55ef874291ffc2ba884e93d`, Ready/open/mergeable, and directly based on protected central `main@ebc69a4016f7668beaef5e3b592d378f22ada684`. Ordinary reverse PR #2185 performed the semantic non-force merge of the protected advance, preserving both #2106's seven-path v1/v2 settlement delta and the protected OpenCode `python/` source-root changelog/product-gap evidence. The old protected-handler dispatch bound to predecessor tuple `#2106@1ba96e.../828eaa...` is historical and cannot authorize this head. Current classification is **SOURCE_REPAIRED / CURRENT_MAIN_RECONCILED / EXACT_HEAD_ACCEPTANCE_PENDING**. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. + The independent CodeQL deployment-order owner `.github#2106` is exact `44901e45636e655cf84cc609e5fe62789216cde9`, Ready/open/mergeable, and directly based on protected central `main@7f07029381a9ca770d0a68b7f3938dd652799d4d`. Ordinary reverse PR #2187 non-force merged the protected advance into the canonical branch, preserving both #2106's seven-path v1/v2 settlement delta and the newly protected Semgrep/security/product-gap changes. All checks and reviews on predecessor `4288590362282074d55ef874291ffc2ba884e93d` are historical and do not transfer. Current classification is **SOURCE_REPAIRED / CURRENT_MAIN_RECONCILED / EXACT_HEAD_ACCEPTANCE_PENDING**. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. 2. **Lifecycle/outbox convergence.** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. From b70d57144ca3cb83c01e0f063030a12aa0ddcabd Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 14 Sep 2026 18:20:20 +0900 Subject: [PATCH 31/57] docs(gap): make central owner topology durable --- docs/product-technical-gap-baseline.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index fa93b678b..ac7099652 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -30,19 +30,19 @@ PR #324 on `fix/result-application-semantic-identifiers` is the documentation-on The active lifecycle/outbox security work in sibling PR #319 and its direct runtime-column authority child #336 are not part of this branch ancestry. #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` closes runtime final-column parity and `atttypmod` authority on top of #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65`; both remain Draft candidate evidence until normal protected integration. Final documentation convergence must preserve both Result Application and lifecycle/outbox evidence after their source lineages legitimately integrate. -Transient hosted-run state belongs in the live integration ledger (#244) and the owning central PR, not in this baseline. This document records durable ownership, protocol state, integration order, and product gaps so a queued runner or a later receipt does not immediately stale the product contract. +Transient hosted-run state belongs in the live integration ledger (#244) and the owning central PR, not in this baseline. This document records durable ownership, protocol state, integration order, and product gaps so a queued runner, protected-base advance, or later receipt does not immediately stale the product contract. ## Current product / technical gaps 1. **Dependency-root and central review integration.** pg protected `main` remains `5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c`; #233 remains outside it at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. #233 is Ready/open/mergeable, changes only `tests/test_postgres_recovery_evidence_registry.py`, and has no production-source delta, but repository-local GREEN cannot substitute for the live central required-workflow path and qualifying independent approval. - Protected `ContextualWisdomLab/.github/main` is exact `7f07029381a9ca770d0a68b7f3938dd652799d4d` after the protected Semgrep runner-fold and intervening security/tooling advances. Noema owner `.github#2079` is exact `2d27e0c13f9b118ca844f5299b0fcdde420fa66b`, directly based on that protected tip after ordinary non-force reconciliation through reverse PR #2188. The finding↔confirmed-probe relation repair, dedicated changed-location truncation regression, and behavior-specific fixture docstrings remain intact. Because the head moved to absorb the protected central advances, predecessor workflow receipts are historical; the durable classification remains **source repaired / current-main reconciled / exact-head acceptance pending** until the new exact-head required workflows and independent review settle. No predecessor GREEN, manual rerun, no-op wake commit, or threshold weakening may substitute for that evidence. + Protected `ContextualWisdomLab/.github/main` is the integrated central workflow authority. Exact protected tips, current owner heads, helper reconciliation PRs, run IDs, review state, and transient queue status are maintained in #244 and the owning central PRs rather than frozen here. After any protected-base advance, each affected owner must reconcile by ordinary non-force ancestry and reacquire exact-head/current-base checks and review; predecessor GREEN does not transfer. - Scheduler/RCA owner `.github#2170@d493cc4c53d0b77d67ef4af13005dcda8fb33c7f` is also directly based on protected central main after ordinary non-force reconciliation through reverse PR #2189. It retains the exact `(Required OpenCode Review, coverage-evidence)` admission repair and the hosted full-suite `defusedxml` dependency-closure repair. The protected-main advance invalidates predecessor hosted receipts as merge authority, so the reconciled exact head must reacquire its own workflows and qualifying review; no manual rerun, no-op wake commit, suite narrowing, or threshold weakening is valid evidence. + Noema owner `.github#2079` canonically owns the finding↔confirmed-probe relation, changed-location truncation regression, and behavior-specific fixture-docstring contract. Scheduler/RCA owner `.github#2170` canonically owns admission of the exact `(Required OpenCode Review, coverage-evidence)` failure into bounded RCA together with the hosted full-suite dependency-closure repair. Review-sidecar owner `.github#1629` owns the one-shot provider-default preflight boundary: central CI must not author provider/model/group preference, caller token/sampling values, inference retry budgets, paid fallback, or a duplicate shell inference. These owners remain separate from pg product source and must converge through their own protected workflow. - `.github#2094@5f90b418187482e7eee1d295d09145e899853925` retains the trusted `uv`/materializer repair but remains based on predecessor `64f483db9d052322c65bcdf1675d66138156f306` and is currently non-mergeable. It must reconcile normally to current protected central authority rather than receive a pg-side wake commit. + `.github#2094` retains the trusted `uv`/materializer repair. Its live ancestry and acceptance state must be read from the central owner at integration time; pg must not compensate for stale central ancestry with copied materializer logic or a source-neutral wake commit. - The independent CodeQL deployment-order owner `.github#2106` is exact `44901e45636e655cf84cc609e5fe62789216cde9`, Ready/open/mergeable, and directly based on protected central `main@7f07029381a9ca770d0a68b7f3938dd652799d4d`. Ordinary reverse PR #2187 non-force merged the protected advance into the canonical branch, preserving both #2106's seven-path v1/v2 settlement delta and the newly protected Semgrep/security/product-gap changes. All checks and reviews on predecessor `4288590362282074d55ef874291ffc2ba884e93d` are historical and do not transfer. Current classification is **SOURCE_REPAIRED / CURRENT_MAIN_RECONCILED / EXACT_HEAD_ACCEPTANCE_PENDING**. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, or protection bypass is accepted. + The independent CodeQL deployment-order owner is `.github#2106`. Its durable contract is a backward-compatible versioned dispatch handler with one authenticated run-wide settlement owner, followed only after normal protected integration by `.github#2040` ordinary/non-force reconciliation and producer cutover. Cross-repository evidence in the central product-gap record must use complete repository identity rather than ambiguous shorthand. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm, or protection bypass is accepted. 2. **Lifecycle/outbox convergence.** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. From 8b8737d3e068b002b27b62357f140947b92e6eee Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 15 Sep 2026 11:00:58 +0900 Subject: [PATCH 32/57] docs(product): keep gap baseline durable --- docs/product-technical-gap-baseline.md | 40 ++++++++++++-------------- 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index ac7099652..04350ccad 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -18,54 +18,50 @@ The protected contract requires tenant context before persistence/provider work; tenant scope is selected only at an authenticated and authorized host boundary; transaction-local parameterized `set_config` binds that scope; lifecycle lookup/conflict/index authority is tenant-qualified; RLS remains enabled and forced for `NOSUPERUSER NOBYPASSRLS` application roles; migration restores forced RLS atomically; package and Docker schemas remain byte-identical; automatic provider retries remain restricted to reviewed idempotent GET semantics; production statement, branch, and public-docstring coverage remain 100%. -## Result Application source authority +Checkpoint persistence is an authority boundary, not only a shape-validation boundary. A persistence path must reject behavior-bearing checkpoint/container subtypes before member access, detach accepted checkpoint state into package-owned exact primitive authority before CAS/SQL use, and freeze an exact built-in PostgreSQL DSN authority before connector/database I/O without silently trimming or rewriting accepted DSN characters. Invalid authority must fail before database mutation and without reflecting credentials or arbitrary caller-controlled object content. -The canonical source/test parent is PR #277 on `fix/result-application-snapshot-b84f0c9`, exact `db1fffb3bc309bf978470314524c585dc0dc48b9`, based on dependency-root #233 exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. +## Result Application source authority -#277 already owns the Result Application source/test fixes, including the integer-budget regressions that prove bounded snapshot rejection occurs before huge decimal materialization. Its current branch-local repository evidence is GREEN. Those receipts do not transfer across descendant commits or constitute protected-main integration. +PR #277 is the canonical Result Application source/test parent and #233 is its protected-integration dependency root. #277 owns the Result Application source/test fixes, including integer-budget regressions proving bounded snapshot rejection before huge decimal materialization. Exact heads, current bases, checks and review state are live evidence and belong in #244 and the owning PRs rather than this durable baseline. ## Documentation authority and convergence -PR #324 on `fix/result-application-semantic-identifiers` is the documentation-only child of #277. It owns the Result Application naming explanation in `ARCHITECTURE.md`, `CHANGELOG.md`, `docs/doctoring/result-application-semantic-identifiers.md`, and this baseline; it must not regain production/test authority already owned by #277. +PR #324 is the canonical root architecture/CHANGELOG/product-gap documentation lane for this stack. It owns the Result Application naming explanation in `ARCHITECTURE.md`, `CHANGELOG.md`, `docs/doctoring/result-application-semantic-identifiers.md`, and this baseline; it must not regain production/test authority already owned by source PRs. -The active lifecycle/outbox security work in sibling PR #319 and its direct runtime-column authority child #336 are not part of this branch ancestry. #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` closes runtime final-column parity and `atttypmod` authority on top of #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65`; both remain Draft candidate evidence until normal protected integration. Final documentation convergence must preserve both Result Application and lifecycle/outbox evidence after their source lineages legitimately integrate. +The lifecycle/outbox security lineage remains owned by #319 and its direct runtime-column authority child #336. Their relation-lock, catalog/role/program authority and final-column/`atttypmod` runtime parity remain source concerns until normal protected integration. Final documentation convergence must preserve both Result Application and lifecycle/outbox evidence after their source lineages legitimately integrate. -Transient hosted-run state belongs in the live integration ledger (#244) and the owning central PR, not in this baseline. This document records durable ownership, protocol state, integration order, and product gaps so a queued runner, protected-base advance, or later receipt does not immediately stale the product contract. +Transient protected tips, branch heads, helper reconciliation identities, hosted-run IDs, review state, release inventory and queue state belong in the live integration ledger (#244) and their owning PRs. This document records durable ownership, protocol state, integration order and product gaps so normal branch/base movement does not immediately stale the product contract. ## Current product / technical gaps -1. **Dependency-root and central review integration.** pg protected `main` remains `5913c4bad79d6bc29d7cc1c624abb7db2ea6a77c`; #233 remains outside it at exact `01d231fde23b82e2ced258d7bfcb4721ed75706d`. #233 is Ready/open/mergeable, changes only `tests/test_postgres_recovery_evidence_registry.py`, and has no production-source delta, but repository-local GREEN cannot substitute for the live central required-workflow path and qualifying independent approval. - - Protected `ContextualWisdomLab/.github/main` is the integrated central workflow authority. Exact protected tips, current owner heads, helper reconciliation PRs, run IDs, review state, and transient queue status are maintained in #244 and the owning central PRs rather than frozen here. After any protected-base advance, each affected owner must reconcile by ordinary non-force ancestry and reacquire exact-head/current-base checks and review; predecessor GREEN does not transfer. - - Noema owner `.github#2079` canonically owns the finding↔confirmed-probe relation, changed-location truncation regression, and behavior-specific fixture-docstring contract. Scheduler/RCA owner `.github#2170` canonically owns admission of the exact `(Required OpenCode Review, coverage-evidence)` failure into bounded RCA together with the hosted full-suite dependency-closure repair. Review-sidecar owner `.github#1629` owns the one-shot provider-default preflight boundary: central CI must not author provider/model/group preference, caller token/sampling values, inference retry budgets, paid fallback, or a duplicate shell inference. These owners remain separate from pg product source and must converge through their own protected workflow. +1. **Dependency-root and central review integration.** #233 remains the protected-integration dependency root. It is test-only and repository-local acceptance cannot substitute for the live central required-workflow path or qualifying independent approval. Protected `.github/main` is the integrated central workflow authority; exact owner heads, helper PRs, run IDs, review state and transient queue state must be read from #244 and the owning central PR immediately before mutation or merge. - `.github#2094` retains the trusted `uv`/materializer repair. Its live ancestry and acceptance state must be read from the central owner at integration time; pg must not compensate for stale central ancestry with copied materializer logic or a source-neutral wake commit. + Noema owner `.github#2079` owns finding↔confirmed-probe relation semantics and changed-location truncation behavior. Scheduler/RCA owner `.github#2170` owns the Required OpenCode coverage-RCA/full-suite dependency path. Review-sidecar owner `.github#1629` owns one-shot provider-default preflight admission without caller-authored provider/model/group preference, token/sampling values, inference retry budgets, paid fallback or duplicate shell inference. `.github#2094` retains the trusted `uv`/materializer repair. - The independent CodeQL deployment-order owner is `.github#2106`. Its durable contract is a backward-compatible versioned dispatch handler with one authenticated run-wide settlement owner, followed only after normal protected integration by `.github#2040` ordinary/non-force reconciliation and producer cutover. Cross-repository evidence in the central product-gap record must use complete repository identity rather than ambiguous shorthand. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm, or protection bypass is accepted. + The independent CodeQL deployment-order owner is `.github#2106`. Its durable contract is a backward-compatible versioned dispatch handler with one authenticated run-wide settlement owner, followed only after normal protected integration by `.github#2040` ordinary/non-force reconciliation and producer cutover. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm or protection bypass is accepted. -2. **Lifecycle/outbox convergence.** #319 exact `7b1864028d952c233abf1318e8b8b0c3351c5b65` and direct child #336 exact `96776b7adfd62ab41c2f5e7cd85ba7e0517fa64a` remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and 14-column plus `atttypmod` runtime parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. +2. **Lifecycle/outbox convergence.** #319 and direct child #336 remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and complete runtime-column/`atttypmod` parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. -3. **Database wait envelope and transaction recovery.** Issue #122 remains open because protected product code does not yet enforce one package-wide policy for package-owned connection acquisition, statement duration, and lock wait. Draft driver foundation #323 exact `34858ef2f96307273853901bef932ec2958e4931` already provides the canonical post-integration acquisition primitive, `PostgresDriverPort.connect(..., connect_timeout_seconds=...)`. Its admitted pg8000 adapter validates a positive finite timeout and forwards it as the DB-API `timeout=` keyword after parsing the existing selector; it does not forward or rewrite the original credential-bearing DSN merely to inject the timeout. Therefore #122 must not introduce a competing timeout API. After #323 integrates, the remaining causal work is an operation-class call-site budget, package-owned PostgreSQL statement/lock budgets, cancellation→rollback/recovery evidence, and real PostgreSQL proof that LLM/provider/network or long CPU/GPU work does not retain an avoidable transaction or lock. Caller-owned/injected transaction authority, including Result Application's atomic result/checkpoint seam, remains outside package-side silent reconfiguration. +3. **Database wait envelope and transaction recovery.** Issue #122 remains open because protected product code does not yet enforce one package-wide policy for package-owned connection acquisition, statement duration and lock wait. Driver foundation #323 owns the canonical post-integration acquisition primitive, `PostgresDriverPort.connect(..., connect_timeout_seconds=...)`; #122 must reuse it rather than introduce a competing timeout API. After #323 integrates, the remaining causal work is operation-class acquisition policy, package-owned PostgreSQL statement/lock budgets, cancellation→rollback/recovery evidence, and real PostgreSQL proof that LLM/provider/network or long CPU/GPU work does not retain an avoidable transaction or lock. Caller-owned/injected transaction authority, including Result Application's atomic result/checkpoint seam, remains outside package-side silent reconfiguration. -4. **Diagnostic privacy and warning hygiene.** Protected `main` still contains diagnostic surfaces whose privacy repairs are unshipped branch candidates. Draft #323 exact `34858ef2f96307273853901bef932ec2958e4931` is the PostgreSQL-driver foundation; Draft #202 exact `b8fd11a93cbaea851b7ea8166f9a28d46b92fe33` is its serialized `ValidationError` privacy child; Draft #344 exact `03be5eaca49c7c76922df8545dcc4f72842567e8` is the token-limit identity-privacy child; TLS child #342 exact `d59df8ff14f8d82ac01f866cb38889407634cc46` remains stacked on the driver foundation. Their branch-local GREEN does not make them shipped truth. Warning-hygiene children remain correctly serialized behind #233: #251 exact `07057cf916e1105a1ddd262d48327a4d3f01500e` owns the schema-finalizer warning repair and #252 exact `e3668344af050672387ca58e59ea24d23d98e51b` owns the compose/runpy RuntimeWarning repair. Warnings and deprecations are root-cause findings, not suppressible noise. +4. **Checkpoint persistence authority.** Issues #289 and #290 remain open defects and are serialized into canonical checkpoint-store writer #323 rather than a competing branch. The repair contract is exact-type admission before caller-controlled behavior can execute, one package-owned checkpoint primitive snapshot used for validation/CAS/SQL, exact built-in DSN authority before connector handoff, unchanged tenant/idempotency/BIGINT/identity invariants, and failure before database I/O for invalid authority. Test-first evidence on the current writer must become exact-head GREEN before production acceptance; mutable heads and run state stay in #244/#323. -5. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including the 14-column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation, and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 currently own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. +5. **Diagnostic privacy and warning hygiene.** Protected behavior still has unshipped privacy and warning repairs. #202 is the serialized `ValidationError` privacy child of driver foundation #323; #344 owns token-limit identity privacy; #342 owns the separate remote PostgreSQL TLS/server-identity child. Warning-hygiene children #251 and #252 remain serialized behind #233 and own the schema-finalizer and compose/runpy warning root causes. Warnings and deprecations are findings to repair or explicitly own, not suppressible noise. Branch-local GREEN does not make any of these shipped truth. -6. **Provider-neutral review transport and immutable CO release.** Protected `contextual-orchestrator/main` remains exact `767e67fbc6b881a452761f32abb69b9971b9b03b`, where the implicit model request timeout was removed. Historical multi-ready Noema timeouts have a source owner in `contextual-orchestrator#1176@a9cb8c6749008904815c663ebd8f8fff7099d6ae`, directly based on that protected tip: virtual selectors may advance across ambiguous transport timeouts while explicit concrete-model requests remain single-shot/fail-closed. #1176 is Ready/open/mergeable but remains unintegrated and unreleased. +6. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including complete column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. - Packaging prerequisite #995 remains exact `29b7f5457ee6a9c2a1f25f1e564f798d419bacc9`, Ready but non-mergeable on stale base `012beaacd0631f8cd3391c77744eeb626269b5de`. Canonical immutable-release owner #1030 is exact `c525ae41a7bb6b6816551094742ea0ef96b48544`, but remains Draft/non-mergeable on stale base `414f22973658c4ddc3d4320fcf7acd9b4e8ba991`; historical head values in its body are not current authority. A protected source SHA, sidecar pin, branch-local GREEN, or mergeable PR is not a released API/client/schema contract. +7. **Provider-neutral review transport and immutable CO release.** `contextual-orchestrator` owns provider/model routing, timeout semantics and the released agent API/client/schema boundary. The multi-ready Noema timeout repair remains owned by `contextual-orchestrator#1176`; packaging prerequisite #995 and immutable-release owner #1030 must reach their own normal protected integration path before consumers can claim a released contract. Mutable branch heads, protected source SHAs, sidecar pins or branch-local GREEN are not release authority. The required order is owner RED -> causal source repair -> exact-head GREEN -> protected integration -> version/CHANGELOG/tag/package -> exact-commit SBOM/provenance/reproducibility/rollback -> immutable Release -> thin consumer pin/canary. Central Actions model-backed workflows may consume only the released CO boundary through a gateway token and `orchestrator/free`; provider/model/group secrets or paid fallback remain CO-owned and must not be hard-coded in pg or central leaf workflows. -7. **Consumer integration.** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. pg owns its PostgreSQL/domain truth; foundation repositories contribute only versioned released contracts and ACLs. +8. **Consumer integration.** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. pg owns its PostgreSQL/domain truth; foundation repositories contribute only versioned released contracts and ACLs. ## Security / operability baseline -The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. +The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. Long-running LLM/provider/model computation must occur outside an explicit PostgreSQL transaction and without holding avoidable database locks. A transaction may protect the minimal aggregate state transition before or after external work; it must not remain idle while waiting for remote inference or CPU/GPU computation. ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local, or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. \ No newline at end of file +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. From 9c9cd7e186867c42f401e5476e635b230342306b Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 15 Sep 2026 16:09:02 +0900 Subject: [PATCH 33/57] docs(product): add licensing and recovery buyer gaps --- docs/product-technical-gap-baseline.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 04350ccad..e8b9210e7 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -44,17 +44,21 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 3. **Database wait envelope and transaction recovery.** Issue #122 remains open because protected product code does not yet enforce one package-wide policy for package-owned connection acquisition, statement duration and lock wait. Driver foundation #323 owns the canonical post-integration acquisition primitive, `PostgresDriverPort.connect(..., connect_timeout_seconds=...)`; #122 must reuse it rather than introduce a competing timeout API. After #323 integrates, the remaining causal work is operation-class acquisition policy, package-owned PostgreSQL statement/lock budgets, cancellation→rollback/recovery evidence, and real PostgreSQL proof that LLM/provider/network or long CPU/GPU work does not retain an avoidable transaction or lock. Caller-owned/injected transaction authority, including Result Application's atomic result/checkpoint seam, remains outside package-side silent reconfiguration. -4. **Checkpoint persistence authority.** Issues #289 and #290 remain open defects and are serialized into canonical checkpoint-store writer #323 rather than a competing branch. The repair contract is exact-type admission before caller-controlled behavior can execute, one package-owned checkpoint primitive snapshot used for validation/CAS/SQL, exact built-in DSN authority before connector handoff, unchanged tenant/idempotency/BIGINT/identity invariants, and failure before database I/O for invalid authority. Test-first evidence on the current writer must become exact-head GREEN before production acceptance; mutable heads and run state stay in #244/#323. +4. **Checkpoint persistence authority.** Issues #289 and #290 remain open defects and are serialized into canonical checkpoint-store writer #323 rather than a competing branch. The repair contract is exact-type admission before caller-controlled behavior can execute, one package-owned checkpoint primitive snapshot used for validation/CAS/SQL, exact built-in DSN authority before connector handoff, unchanged tenant/idempotency/BIGINT/identity invariants, and failure before database I/O for invalid authority. Test-first evidence and its causal repair must become exact-final-head GREEN before production acceptance; mutable heads and run state stay in #244/#323. 5. **Diagnostic privacy and warning hygiene.** Protected behavior still has unshipped privacy and warning repairs. #202 is the serialized `ValidationError` privacy child of driver foundation #323; #344 owns token-limit identity privacy; #342 owns the separate remote PostgreSQL TLS/server-identity child. Warning-hygiene children #251 and #252 remain serialized behind #233 and own the schema-finalizer and compose/runpy warning root causes. Warnings and deprecations are findings to repair or explicitly own, not suppressible noise. Branch-local GREEN does not make any of these shipped truth. -6. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including complete column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. +6. **Commercial runtime-license closure.** Issue #322 remains a release defect until the production PostgreSQL dependency graph actually ships without the superseded Psycopg runtime dependency. #323 owns the driver migration and must preserve reviewed `PostgresDriverPort` behavior, pg8000 runtime identity, fail-closed service/DSN authority and exact dependency/license/SBOM evidence through normal protected integration. A branch-local replacement, package build, version literal or SBOM is insufficient: the accepted protected source and dependency graph must be bound to the immutable release artifacts, provenance, reproducibility and rollback evidence that buyers receive. -7. **Provider-neutral review transport and immutable CO release.** `contextual-orchestrator` owns provider/model routing, timeout semantics and the released agent API/client/schema boundary. The multi-ready Noema timeout repair remains owned by `contextual-orchestrator#1176`; packaging prerequisite #995 and immutable-release owner #1030 must reach their own normal protected integration path before consumers can claim a released contract. Mutable branch heads, protected source SHAs, sidecar pins or branch-local GREEN are not release authority. +7. **Disaster-recovery and PITR acquisition closure.** Issue #204 remains the buyer-visible recovery umbrella. Protected `main` has bounded logical backup/restore, receipt, catalog/index, cluster-isolation and physical/WAL/PITR profile primitives, while the active recovery program continues to decompose physical backup, continuous WAL evidence, timeline/history assessment, deterministic PITR target binding/replay, restored tenant-RLS authentication and isolated application-readiness checks. None of those branch-local slices alone proves end-to-end DR. A commercially defensible claim requires composition on a genuinely isolated target, exact protected source/schema/backup identity, WAL continuity and timeline ancestry, deterministic replay to an explicit target, corruption/interruption/wrong-cluster/version failure behavior, bounded resource use, application readiness, and deployment-specific achieved RPO/RTO. External custody for TLS material, Fernet keys, provider credentials/files, host/object storage and telemetry remains an explicit host/operator boundary rather than repository-owned recoverable content. + +8. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including complete column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. + +9. **Provider-neutral review transport and immutable CO release.** `contextual-orchestrator` owns provider/model routing, timeout semantics and the released agent API/client/schema boundary. The multi-ready Noema timeout repair remains owned by `contextual-orchestrator#1176`; packaging prerequisite #995 and immutable-release owner #1030 must reach their own normal protected integration path before consumers can claim a released contract. Mutable branch heads, protected source SHAs, sidecar pins or branch-local GREEN are not release authority. The required order is owner RED -> causal source repair -> exact-head GREEN -> protected integration -> version/CHANGELOG/tag/package -> exact-commit SBOM/provenance/reproducibility/rollback -> immutable Release -> thin consumer pin/canary. Central Actions model-backed workflows may consume only the released CO boundary through a gateway token and `orchestrator/free`; provider/model/group secrets or paid fallback remain CO-owned and must not be hard-coded in pg or central leaf workflows. -8. **Consumer integration.** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. pg owns its PostgreSQL/domain truth; foundation repositories contribute only versioned released contracts and ACLs. +10. **Consumer integration.** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. pg owns its PostgreSQL/domain truth; foundation repositories contribute only versioned released contracts and ACLs. ## Security / operability baseline @@ -64,4 +68,4 @@ Long-running LLM/provider/model computation must occur outside an explicit Postg ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. \ No newline at end of file From ec91141818bc80e1716542cda69155a37de11875 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Tue, 15 Sep 2026 21:04:41 +0900 Subject: [PATCH 34/57] docs(recovery): document bounded PITR target observation --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b203641c..5e63881c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +- Bounded read-only PostgreSQL PITR target-configuration observation on a caller-owned already-connected isolated recovery target. The observer reads exactly eight recovery-target settings plus `pg_is_in_recovery()`, uses bounded result materialization, fails closed on malformed, duplicate, oversized, pending-restart, inactive-recovery, or mismatched evidence, and returns content-free live observation provenance. It does not write recovery configuration, create `recovery.signal`, supply `restore_command`, prove WAL/archive/timeline completeness or target attainment, promote recovery, prove application readiness, or establish achieved RPO/RTO or DR capability. - Bounded `restore_postgres_logical_backup()` executor that runs one shell-free `pg_restore --single-transaction --exit-on-error` against a caller-owned private archive descriptor. Callers must pass exact-boolean @@ -157,4 +158,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Initial standalone and embeddable PostgreSQL LLM batch engine extraction. +- Initial standalone and embeddable PostgreSQL LLM batch engine extraction. \ No newline at end of file From d6d7bbadaa8e0bc0645b66752c1ff49d1def2f9b Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 16 Sep 2026 02:16:56 +0900 Subject: [PATCH 35/57] docs(product): record provider-port convergence gap --- docs/product-technical-gap-baseline.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index e8b9210e7..0a359fac9 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -6,7 +6,7 @@ ## Bounded-context map -- **Provider Batch Gateway:** provider-neutral batch inference and provider HTTP/file adapters. External provider identifiers remain adapter contracts rather than internal domain authority. +- **Provider Batch Gateway:** target provider-neutral batch inference through `BatchInferencePort`; the current direct provider HTTP/file client remains an implementation debt until #318 moves provider/model/key authority behind a released Contextual-Orchestrator contract. External provider identifiers remain adapter contracts rather than internal domain authority. - **Durable Batch Lifecycle:** tenant-scoped lifecycle persistence with business identity `(tenant_scope, endpoint_alias, remote_batch_id)`, forced PostgreSQL RLS, and durable transition evidence. - **Result Streaming:** bounded provider JSONL decoding and resumable `BatchResultCheckpoint` evidence. - **Result Application:** applies one `CheckpointedBatchResultRecord` effect and advances its checkpoint in the same caller-owned transaction. Package-owned vocabulary is `transaction_cursor`, `checkpointed_record`, `record_effect`, `record_applied`, and `result_checkpoint`; historical public Python names remain compatibility adapters. @@ -18,7 +18,7 @@ The protected contract requires tenant context before persistence/provider work; tenant scope is selected only at an authenticated and authorized host boundary; transaction-local parameterized `set_config` binds that scope; lifecycle lookup/conflict/index authority is tenant-qualified; RLS remains enabled and forced for `NOSUPERUSER NOBYPASSRLS` application roles; migration restores forced RLS atomically; package and Docker schemas remain byte-identical; automatic provider retries remain restricted to reviewed idempotent GET semantics; production statement, branch, and public-docstring coverage remain 100%. -Checkpoint persistence is an authority boundary, not only a shape-validation boundary. A persistence path must reject behavior-bearing checkpoint/container subtypes before member access, detach accepted checkpoint state into package-owned exact primitive authority before CAS/SQL use, and freeze an exact built-in PostgreSQL DSN authority before connector/database I/O without silently trimming or rewriting accepted DSN characters. Invalid authority must fail before database mutation and without reflecting credentials or arbitrary caller-controlled object content. +Checkpoint persistence is an authority boundary, not only a shape-validation boundary. A persistence path must reject behavior-bearing checkpoint/container subtypes before member access, detach accepted checkpoint state into package-owned exact primitive authority before CAS/SQL use, and freeze exact built-in PostgreSQL DSN and persistence-key string authority before normalization, connector/database I/O, SQL binding, or store retention without silently trimming or rewriting accepted identity characters. Invalid authority must fail before database mutation and without reflecting credentials or arbitrary caller-controlled object content. ## Result Application source authority @@ -44,7 +44,7 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 3. **Database wait envelope and transaction recovery.** Issue #122 remains open because protected product code does not yet enforce one package-wide policy for package-owned connection acquisition, statement duration and lock wait. Driver foundation #323 owns the canonical post-integration acquisition primitive, `PostgresDriverPort.connect(..., connect_timeout_seconds=...)`; #122 must reuse it rather than introduce a competing timeout API. After #323 integrates, the remaining causal work is operation-class acquisition policy, package-owned PostgreSQL statement/lock budgets, cancellation→rollback/recovery evidence, and real PostgreSQL proof that LLM/provider/network or long CPU/GPU work does not retain an avoidable transaction or lock. Caller-owned/injected transaction authority, including Result Application's atomic result/checkpoint seam, remains outside package-side silent reconfiguration. -4. **Checkpoint persistence authority.** Issues #289 and #290 remain open defects and are serialized into canonical checkpoint-store writer #323 rather than a competing branch. The repair contract is exact-type admission before caller-controlled behavior can execute, one package-owned checkpoint primitive snapshot used for validation/CAS/SQL, exact built-in DSN authority before connector handoff, unchanged tenant/idempotency/BIGINT/identity invariants, and failure before database I/O for invalid authority. Test-first evidence and its causal repair must become exact-final-head GREEN before production acceptance; mutable heads and run state stay in #244/#323. +4. **Checkpoint persistence authority.** Issues #289, #290 and #346 remain open defects and are serialized into canonical checkpoint-store writer #323 rather than competing branches. The repair contract is exact-type admission before caller-controlled behavior can execute, one package-owned checkpoint primitive snapshot used for validation/CAS/SQL, exact built-in DSN authority before connector handoff, and exact built-in persistence-key authority before normalization, SQL binding, tenant retention or database I/O. #346 has already established real hosted RED for behavior-bearing `consumer_name`, `tenant_scope`, `batch_id` and `endpoint_alias` string subtypes and has a minimum local production repair; that repair still requires its own exact-final-head GREEN and normal protected integration. Tenant/RLS, idempotency, BIGINT and identity invariants remain unchanged; mutable heads and run state stay in #244/#323. 5. **Diagnostic privacy and warning hygiene.** Protected behavior still has unshipped privacy and warning repairs. #202 is the serialized `ValidationError` privacy child of driver foundation #323; #344 owns token-limit identity privacy; #342 owns the separate remote PostgreSQL TLS/server-identity child. Warning-hygiene children #251 and #252 remain serialized behind #233 and own the schema-finalizer and compose/runpy warning root causes. Warnings and deprecations are findings to repair or explicitly own, not suppressible noise. Branch-local GREEN does not make any of these shipped truth. @@ -60,6 +60,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 10. **Consumer integration.** `contextual-orchestrator` and other CWL hosts must consume released package/API/schema contracts and provide authenticated tenant context. Mutable branch dependencies, copied package source, cross-service SQL, or an unreleased CO branch SHA used as product authority remain prohibited. pg owns its PostgreSQL/domain truth; foundation repositories contribute only versioned released contracts and ACLs. +11. **Provider-neutral `BatchInferencePort` convergence.** Issue #318 remains the canonical architecture gap between pg's target provider-neutral ownership and the current direct OpenAI-compatible `/files` + `/batches` client implementation. The direct client is not itself the desired long-term provider/model/key authority. Provider/model discovery, routing/fallback and credential authority must move behind an explicit pg-owned port/ACL that consumes a released Contextual-Orchestrator API/client/schema; branch SHAs, copied CO source, hard-coded provider groups or direct provider credentials are not acceptable substitutes. + + #317 remains the live owner for the current `batch_api_client.py` surface and #347 separately owns its provider-resource-identifier primitive-authority defect. The migration in #318 must therefore preserve #347's security invariant rather than make it disappear by deleting or renaming the direct client: behavior-bearing caller identifiers must be rejected before they can become URL formatting, credential-resolution, transport-preparation, comparison, logging, persistence or evidence authority. Completion requires owner RED -> minimum causal repair -> exact-head GREEN -> normal protected integration -> immutable CO release -> pg consumer pin/canary, followed by removal or restriction of direct provider authority only after successor contract and adversarial evidence are complete. + ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. @@ -68,4 +72,4 @@ Long-running LLM/provider/model computation must occur outside an explicit Postg ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. \ No newline at end of file +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. From aa2491140b7fefbbf0fecd4c100942f780f2718f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 16 Sep 2026 03:06:10 +0900 Subject: [PATCH 36/57] docs(batch): doctor provider-neutral port convergence --- .../batch-inference-port-convergence.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/doctoring/batch-inference-port-convergence.md diff --git a/docs/doctoring/batch-inference-port-convergence.md b/docs/doctoring/batch-inference-port-convergence.md new file mode 100644 index 000000000..439dbe029 --- /dev/null +++ b/docs/doctoring/batch-inference-port-convergence.md @@ -0,0 +1,66 @@ +# BatchInferencePort convergence doctoring + +## Purpose + +`pg-llm-batch` owns durable asynchronous batch lifecycle, token/size accounting, tenant-scoped persistence, checkpoint/result application, and the provider-neutral `BatchInferencePort` boundary. `contextual-orchestrator` owns provider/model discovery, routing/fallback, credential discovery and concrete LLM execution authority. This note prevents a structural Python `Protocol` or a renamed direct HTTP client from being mistaken for that completed authority split. + +This is a doctoring/evidence surface. Mutable branch heads below are dated candidate evidence only and must be refreshed before integration or release decisions. + +## Current evidence snapshot — 2026-09-16 + +Protected `main` remains on the pre-convergence implementation and does not establish a released Contextual-Orchestrator-backed batch adapter. + +Draft #319 at `7b1864028d952c233abf1318e8b8b0c3351c5b65` already contains `pg_llm_batch/batch_inference_port.py` and `tests/test_batch_inference_port.py`. The candidate `BatchInferencePort` exposes upload, create, status, cancel, result-download and file-delete lifecycle operations. Its tests prove that the shipped `BatchAPIClient` and a non-HTTP adapter can satisfy the protocol while discovery/routing methods remain outside the port. + +That is useful candidate evidence, but it is not the end state required by #318: + +- `BatchAPIClient` remains a conforming implementation and still owns direct OpenAI-compatible `/files` + `/batches` HTTP behavior on its active source lineage; +- `create_batch_job` still accepts a host-selected `endpoint` string, so the candidate protocol alone does not prove semantic operation identity is separated from provider wire routing; +- the protocol deliberately permits an arbitrary host adapter and therefore does not itself bind execution to a versioned immutable `contextual-orchestrator` API/client/schema; +- a mutable #319 head is neither protected product truth nor immutable dependency identity. + +Draft #317 remains the active `batch_api_client.py` writer for #301/#302/#347. Issue #201 owns first-class endpoint preparation/accounting. Issue #318 owns the released-contract/ACL convergence. Canonical product documentation remains separated across #229 and #324. No parallel source writer should be created while those paths overlap. + +## Required authority split + +The final boundary must make the following ownership executable rather than descriptive: + +| Concern | Canonical owner | +| --- | --- | +| PostgreSQL durable lifecycle, tenant/RLS, token/size accounting, idempotency, checkpoint/result application | `pg-llm-batch` | +| Provider/model discovery and selection | `contextual-orchestrator` | +| Provider credentials/key discovery | `contextual-orchestrator` | +| Routing, fallback and provider-specific execution semantics | `contextual-orchestrator` | +| Versioned batch lifecycle ACL consumed by pg | pg-owned adapter over an immutable released CO API/client/schema | +| Provider wire identifiers returned as evidence | adapter boundary only; never pg domain authority by themselves | + +No implementation may copy CO source, query another service database, pin a mutable CO branch, hard-code provider/model/group authority, or treat a protected source SHA as a released contract. + +## RED-to-GREEN acceptance + +Before replacing or restricting direct-provider authority, the serialized owner must establish realistic REDs for all of these conditions and then make the minimum causal repair: + +1. **Released-contract admission.** A pg adapter must reject missing, mutable, incompatible or unverifiable CO contract identity and admit only an explicitly supported immutable released API/client/schema identity. +2. **No hidden provider authority.** Durable pg lifecycle callers must not need provider/model/group/key discovery. Provider wire endpoints or route selection must not become hidden authority merely because they are passed through a `Protocol` method. +3. **Primitive authority before transport.** The #347 invariant survives migration: behavior-bearing caller identifiers are rejected before URL formatting, credential resolution, transport preparation, comparison, logging, persistence or evidence retention. +4. **Usage honesty.** Measured, estimated and unavailable usage remain distinguishable. Unknown usage or unknown price is never coerced to zero or an authoritative complete measured total; zero usage remains distinct from unknown price. +5. **Lifecycle semantics.** Submit/status/cancel/result retrieval preserve idempotency, bounded response handling and provider-neutral lifecycle state without inventing unsupported provider behavior. +6. **Termination semantics.** User cancellation, provider terminal state and any administrator policy timeout remain distinguishable. Reasoning, streaming or tool execution is not terminated merely because elapsed time crossed an arbitrary default. +7. **Database transaction boundary.** Remote inference, provider queue wait, retry backoff and long CPU/GPU/tokenization work occur outside avoidable explicit PostgreSQL transactions and locks. Transactions cover only the minimal durable aggregate transition before or after external work. +8. **Standalone compatibility is explicit.** If a direct provider adapter is retained for standalone use, it is a deliberately bounded compatibility adapter with the same security/accounting invariants. It is not silently treated as the production CO-backed authority. + +GREEN requires exact-head repository tests plus the then-live security/SAST/review gates. A predecessor GREEN does not transfer after source/base movement. + +## Migration order + +Use the existing serialized owners rather than creating a sibling implementation: + +1. settle #317/#347 and the overlapping endpoint/accounting writers with their own RED→repair→exact-head evidence; +2. repeat #316's open-PR and no-PR path census for `batch_inference_port.py`, `batch_api_client.py`, endpoint preparation/accounting, package exports and tests; +3. obtain an eligible immutable CO release from the current CO release owner and verify API/client/schema identity, SBOM/provenance/reproducibility and rollback evidence; +4. author the pg ACL REDs against that released boundary, then implement the minimum adapter/port repair without source copying or cross-service SQL; +5. ordinary/non-force reconcile descendants, reacquire exact-final-head evidence, converge #229/#324 documentation, and only then promote an immutable pg release and consumer canary. + +## Release claim boundary + +A protocol class, branch-local test, protected commit, successful Release Acceptance workflow, package build or documentation statement is not an immutable release. Completion requires a normally integrated protected exact head and verified version/CHANGELOG/tag/package/SBOM/provenance/reproducibility/rollback artifacts. The consuming pg release must bind to the eligible immutable CO contract it actually uses. \ No newline at end of file From 9c4666f666df116595097c9be59247336e7f2287 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 16 Sep 2026 08:02:26 +0900 Subject: [PATCH 37/57] docs(gap): mark checkpoint repair exact-head green --- docs/product-technical-gap-baseline.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 0a359fac9..54bff893e 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -44,7 +44,7 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 3. **Database wait envelope and transaction recovery.** Issue #122 remains open because protected product code does not yet enforce one package-wide policy for package-owned connection acquisition, statement duration and lock wait. Driver foundation #323 owns the canonical post-integration acquisition primitive, `PostgresDriverPort.connect(..., connect_timeout_seconds=...)`; #122 must reuse it rather than introduce a competing timeout API. After #323 integrates, the remaining causal work is operation-class acquisition policy, package-owned PostgreSQL statement/lock budgets, cancellation→rollback/recovery evidence, and real PostgreSQL proof that LLM/provider/network or long CPU/GPU work does not retain an avoidable transaction or lock. Caller-owned/injected transaction authority, including Result Application's atomic result/checkpoint seam, remains outside package-side silent reconfiguration. -4. **Checkpoint persistence authority.** Issues #289, #290 and #346 remain open defects and are serialized into canonical checkpoint-store writer #323 rather than competing branches. The repair contract is exact-type admission before caller-controlled behavior can execute, one package-owned checkpoint primitive snapshot used for validation/CAS/SQL, exact built-in DSN authority before connector handoff, and exact built-in persistence-key authority before normalization, SQL binding, tenant retention or database I/O. #346 has already established real hosted RED for behavior-bearing `consumer_name`, `tenant_scope`, `batch_id` and `endpoint_alias` string subtypes and has a minimum local production repair; that repair still requires its own exact-final-head GREEN and normal protected integration. Tenant/RLS, idempotency, BIGINT and identity invariants remain unchanged; mutable heads and run state stay in #244/#323. +4. **Checkpoint persistence authority.** Issues #289, #290 and #346 remain open defects and are serialized into canonical checkpoint-store writer #323 rather than competing branches. The repair contract is exact-type admission before caller-controlled behavior can execute, one package-owned checkpoint primitive snapshot used for validation/CAS/SQL, exact built-in DSN authority before connector handoff, and exact built-in persistence-key authority before normalization, SQL binding, tenant retention or database I/O. #346 established real hosted RED for behavior-bearing `consumer_name`, `tenant_scope`, `batch_id` and `endpoint_alias` string subtypes; its minimum local production repair has now reached exact-head repository GREEN on the canonical Draft #323 generation. That evidence is not protected integration or immutable release authority, so #346 remains open until the invariant reaches protected `main` through normal governance. Tenant/RLS, idempotency, BIGINT and identity invariants remain unchanged; mutable heads and run state stay in #244/#323. 5. **Diagnostic privacy and warning hygiene.** Protected behavior still has unshipped privacy and warning repairs. #202 is the serialized `ValidationError` privacy child of driver foundation #323; #344 owns token-limit identity privacy; #342 owns the separate remote PostgreSQL TLS/server-identity child. Warning-hygiene children #251 and #252 remain serialized behind #233 and own the schema-finalizer and compose/runpy warning root causes. Warnings and deprecations are findings to repair or explicitly own, not suppressible noise. Branch-local GREEN does not make any of these shipped truth. From 66cb316651aa172f595167ee4a8338141551756c Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 16 Sep 2026 21:37:14 +0900 Subject: [PATCH 38/57] docs(changelog): restore physical PITR profile release note --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e63881c8..229eb171c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Bounded read-only PostgreSQL PITR target-configuration observation on a caller-owned already-connected isolated recovery target. The observer reads exactly eight recovery-target settings plus `pg_is_in_recovery()`, uses bounded result materialization, fails closed on malformed, duplicate, oversized, pending-restart, inactive-recovery, or mismatched evidence, and returns content-free live observation provenance. It does not write recovery configuration, create `recovery.signal`, supply `restore_command`, prove WAL/archive/timeline completeness or target attainment, promote recovery, prove application readiness, or establish achieved RPO/RTO or DR capability. +- Caller-owned physical/WAL/PITR recovery profile binder + (`bind_postgres_physical_recovery_profile()` / + `parse_postgres_physical_recovery_profile()`). The seam records method, + recovery-target kind, continuous-WAL necessity, isolated-target readiness, + and optional RPO/RTO objectives without executing backup or restore. + `wal_archive_required=False` means no continuous archive, not the absence of + backup-internal WAL. `pitr` plus `immediate` is a consistent-state stop, not + replay-to-end-of-archive. Lone-surrogate profile text fails as + `PostgresPhysicalRecoveryError`. - Bounded `restore_postgres_logical_backup()` executor that runs one shell-free `pg_restore --single-transaction --exit-on-error` against a caller-owned private archive descriptor. Callers must pass exact-boolean From cc52c4367106bd650f3e34a50c7dafa3ce4be7e6 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 17 Sep 2026 16:02:00 +0900 Subject: [PATCH 39/57] docs(product): record provider retention authority gap --- docs/product-technical-gap-baseline.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 54bff893e..e6805b618 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -64,6 +64,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted #317 remains the live owner for the current `batch_api_client.py` surface and #347 separately owns its provider-resource-identifier primitive-authority defect. The migration in #318 must therefore preserve #347's security invariant rather than make it disappear by deleting or renaming the direct client: behavior-bearing caller identifiers must be rejected before they can become URL formatting, credential-resolution, transport-preparation, comparison, logging, persistence or evidence authority. Completion requires owner RED -> minimum causal repair -> exact-head GREEN -> normal protected integration -> immutable CO release -> pg consumer pin/canary, followed by removal or restriction of direct provider authority only after successor contract and adversarial evidence are complete. +12. **Provider content retention, deletion and erasure authority.** Issue #136 remains a buyer-visible content-lifecycle gap even though protected product code already exposes bounded provider-file expiry inputs and explicit caller-authorized `delete_file()` primitives. Those primitives do not prove that every compatible provider accepts retention fields, that a terminal batch authorizes deletion, that already-deleted/not-found responses are reconciled correctly, or that transient/uncertain deletion failures can be treated as success. They also do not establish crash/restart-safe automatic cleanup, durable cleanup audit, local PostgreSQL retention/export/erasure, backup erasure, host-log erasure, cryptographic erasure or legal-erasure guarantees. + + Residual source work must remain serialized behind the active `batch_api_client.py` writer #317 until that owner reaches protected integration or a verified successor completely inherits its valid delta. Completion requires an explicit provider capability/compatibility contract, reviewed already-deleted/not-found and uncertain-failure reconciliation semantics, explicit deletion authority that is never inferred from lifecycle terminality alone, bounded content-free evidence that survives remote file disappearance, and strict separation of remote-provider retention from local PostgreSQL, backup, telemetry and host-storage authorities. #195/#196 retain repository-wide threat/data-governance ownership; #229/#321/#324 retain their existing canonical documentation surfaces rather than spawning a competing retention-doc writer. + ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. From 8baa512b4e82d9381905e6aea38c7456478fffad Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 17 Sep 2026 17:04:54 +0900 Subject: [PATCH 40/57] docs(product): record content-bearing tenant isolation gap --- docs/product-technical-gap-baseline.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index e6805b618..08c757533 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -68,6 +68,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Residual source work must remain serialized behind the active `batch_api_client.py` writer #317 until that owner reaches protected integration or a verified successor completely inherits its valid delta. Completion requires an explicit provider capability/compatibility contract, reviewed already-deleted/not-found and uncertain-failure reconciliation semantics, explicit deletion authority that is never inferred from lifecycle terminality alone, bounded content-free evidence that survives remote file disappearance, and strict separation of remote-provider retention from local PostgreSQL, backup, telemetry and host-storage authorities. #195/#196 retain repository-wide threat/data-governance ownership; #229/#321/#324 retain their existing canonical documentation surfaces rather than spawning a competing retention-doc writer. +13. **Content-bearing tenant/RLS completion.** Issue #130 remains a buyer-visible isolation gap. Protected `main` force-enables RLS for durable remote lifecycle state and result-stream checkpoints, but the protected schema still contains shared `llm_queues` and `llm_batches` state without one proven tenant-qualified relational/RLS boundary. `llm_batches` can retain model identity, token/accounting values, input/output file paths and error text, so lifecycle/checkpoint RLS must not be overclaimed as package-wide isolation of content-bearing work state. + + Completion requires a fresh changed-path/no-PR writer census before source mutation, realistic two-tenant PostgreSQL RED evidence under the same ordinary application role, one trusted host-selected tenant authority that is never derived from provider/request/model content, tenant-qualified root identities and relational constraints across reviewed content-bearing state, FORCE RLS with default-deny missing context for tenant-owned tables, and explicit review of deliberately deployment-global objects rather than tenant-duplicating them for symmetry. Existing-volume migration/backfill must be atomic and fail closed on ambiguous historical ownership without discarding non-empty content. Cross-tenant SELECT/INSERT/UPDATE/DELETE, same-tenant operation, standalone compatibility, rollback/restart/recovery and tenant-qualified uniqueness/join/cascade/idempotency behavior require real PostgreSQL acceptance. Tenant binding remains transaction-local to the minimal database aggregate transition; provider/model/network waits or long CPU/GPU work must not keep an avoidable PostgreSQL transaction or lock open merely to retain tenant context. Source work stays serialized behind the then-live schema/database/lifecycle writers identified by the invocation-scoped census; #229/#324 and the security/data-governance owners converge documentation without opening a competing broad tenant/schema branch. + ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. From 6e2d23b0e08e87eb031f3be0059688cc4b94055d Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 17 Sep 2026 18:01:14 +0900 Subject: [PATCH 41/57] docs(product): record async credential concurrency gap --- docs/product-technical-gap-baseline.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 08c757533..ffd96fbff 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -72,6 +72,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires a fresh changed-path/no-PR writer census before source mutation, realistic two-tenant PostgreSQL RED evidence under the same ordinary application role, one trusted host-selected tenant authority that is never derived from provider/request/model content, tenant-qualified root identities and relational constraints across reviewed content-bearing state, FORCE RLS with default-deny missing context for tenant-owned tables, and explicit review of deliberately deployment-global objects rather than tenant-duplicating them for symmetry. Existing-volume migration/backfill must be atomic and fail closed on ambiguous historical ownership without discarding non-empty content. Cross-tenant SELECT/INSERT/UPDATE/DELETE, same-tenant operation, standalone compatibility, rollback/restart/recovery and tenant-qualified uniqueness/join/cascade/idempotency behavior require real PostgreSQL acceptance. Tenant binding remains transaction-local to the minimal database aggregate transition; provider/model/network waits or long CPU/GPU work must not keep an avoidable PostgreSQL transaction or lock open merely to retain tenant context. Source work stays serialized behind the then-live schema/database/lifecycle writers identified by the invocation-scoped census; #229/#324 and the security/data-governance owners converge documentation without opening a competing broad tenant/schema branch. +14. **Async credential-resolution concurrency.** Issue #111 remains a buyer-visible availability and latency gap because the asynchronous provider client can invoke a synchronous credential resolver directly on the event-loop thread, while the package-provided resolver can perform PostgreSQL-backed config/secret reads. Provider HTTP timeout accounting therefore does not bound credential lookup, and a slow or contended lookup can starve unrelated async batch work before provider I/O begins. + + Completion requires deterministic heartbeat/non-starvation RED evidence, an explicit async resolver contract or a bounded compatibility adapter for synchronous resolvers, bounded worker/connection fan-out, a finite credential-resolution cancellation/resource policy distinct from provider HTTP timeout, deterministic cleanup, and realistic concurrent failure/restart evidence. Endpoint alias and gateway URL authority must be validated before credential-bearing provider I/O, diagnostics must not leak secret/URL/DSN/provider content, and plaintext caching must not become an indefinite shortcut. Credential database work may use its own minimal bounded transaction, but no `BEGIN`, row/relation lock or transaction-scoped advisory lock may survive into provider/model/network execution. Source work remains serialized until a fresh intended-path census proves the active provider-client and config/secret writers have normally integrated, been completely inherited by a canonical successor, or are independently non-overlapping; #111 must also preserve #122's package-wide database wait envelope and #318's released Contextual-Orchestrator authority rather than hard-coding provider/model/group policy. + ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. From 4811a74d8ff319584decb61d655332fa74019e99 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 17 Sep 2026 19:04:27 +0900 Subject: [PATCH 42/57] docs(product): record governance succession buyer gap --- docs/product-technical-gap-baseline.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index ffd96fbff..0a3608079 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -76,6 +76,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires deterministic heartbeat/non-starvation RED evidence, an explicit async resolver contract or a bounded compatibility adapter for synchronous resolvers, bounded worker/connection fan-out, a finite credential-resolution cancellation/resource policy distinct from provider HTTP timeout, deterministic cleanup, and realistic concurrent failure/restart evidence. Endpoint alias and gateway URL authority must be validated before credential-bearing provider I/O, diagnostics must not leak secret/URL/DSN/provider content, and plaintext caching must not become an indefinite shortcut. Credential database work may use its own minimal bounded transaction, but no `BEGIN`, row/relation lock or transaction-scoped advisory lock may survive into provider/model/network execution. Source work remains serialized until a fresh intended-path census proves the active provider-client and config/secret writers have normally integrated, been completely inherited by a canonical successor, or are independently non-overlapping; #111 must also preserve #122's package-wide database wait envelope and #318's released Contextual-Orchestrator authority rather than hard-coding provider/model/group policy. +15. **Maintainer succession and governance continuity.** Issue #306 remains a buyer-visible operational-continuity gap. Central `.github#772` owns making the live approval policy structurally satisfiable without self-approval, fictional reviewers, bot-as-human treatment, routine administrator bypass or deterministic-gate weakening; that central policy repair is necessary but does not by itself remove the repository's residual single-person operational dependency across administration, security response, release publication, rollback/recovery, emergency access and acquisition handover. + + Completion requires auditable succession/recovery paths for repository administration and external release/security authorities, onboarding/offboarding and credential/key recovery without repository-embedded secrets, protected-branch and deterministic workflow controls that survive maintainer loss or turnover, and release/rollback authority explicitly separated from build evidence. Future reviewer/CODEOWNERS changes must be enabled only when real least-privilege independent human authority can satisfy them, with dry-run and rollback evidence; at least two humans is an acquisition objective rather than a fabricated prerequisite for today's central merge-policy repair. #306 owns the residual operational-continuity contract, `.github#772` owns central approval-policy satisfiability, and canonical governance prose remains with #229 while this baseline records only the buyer gap. + ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. From cba24230b0178a5d4ae81cce792d39c54445bbc5 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Thu, 17 Sep 2026 23:06:35 +0900 Subject: [PATCH 43/57] docs(product): record FinOps usage completeness buyer gap --- docs/product-technical-gap-baseline.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 0a3608079..e810a9c3d 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -80,6 +80,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires auditable succession/recovery paths for repository administration and external release/security authorities, onboarding/offboarding and credential/key recovery without repository-embedded secrets, protected-branch and deterministic workflow controls that survive maintainer loss or turnover, and release/rollback authority explicitly separated from build evidence. Future reviewer/CODEOWNERS changes must be enabled only when real least-privilege independent human authority can satisfy them, with dry-run and rollback evidence; at least two humans is an acquisition objective rather than a fabricated prerequisite for today's central merge-policy repair. #306 owns the residual operational-continuity contract, `.github#772` owns central approval-policy satisfiability, and canonical governance prose remains with #229 while this baseline records only the buyer gap. +16. **FinOps usage completeness and cost-attribution evidence.** Issue #312 remains a buyer-visible acquisition gap because the existing bounded usage-evidence slice can distinguish provenance authority such as `LOCAL_MEASURED`, `PROVIDER_REPORTED`, `HOST_RATE_ESTIMATE`, and `RECONCILED`, while nullable token counts alone do not preserve every measurement-completeness state needed for auditable cost attribution. In particular, measured zero, provider-unavailable/unknown usage, estimated usage, and a reconciled aggregate containing estimated or unknown components must not collapse into the same representation or disappear from evidence merely because a bounded integer count is absent or available. + + Completion requires a realistic pg-domain RED proving which semantically distinct usage states the current evidence representation cannot preserve, followed by one explicit closed measurement/completeness contract or equivalent lossless representation rather than a mutable provider enum. The released Contextual-Orchestrator ACL in #318 must map upstream usage into that pg-owned contract without coercing unavailable/unknown usage to zero, silently dropping a completed call, or relabeling a mixed aggregate as authoritative measured usage. Evidence remains content-minimal: tenant scope and bounded opaque identifiers/counts/provenance may be retained, but prompts, results, JSONL/business content, provider bodies, credentials, provider/model routing policy, mutable price books and branch SHAs do not become FinOps authority. Pricing and billing settlement remain outside the current evidence primitive unless separately reviewed. Source widening stays on the canonical `usage_evidence.py` writer #315 or its deliberate ordinary/non-force successor after a fresh #316 writer census; this baseline records the buyer contract only and does not open a competing implementation lane. + ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. @@ -88,4 +92,4 @@ Long-running LLM/provider/model computation must occur outside an explicit Postg ## Evidence status -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. +Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. \ No newline at end of file From 4f211dc932ad6501b41bcef493f490fdf4aa8372 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 18 Sep 2026 03:07:09 +0900 Subject: [PATCH 44/57] docs(product): refresh integrated workflow and CO release authority --- docs/product-technical-gap-baseline.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index e810a9c3d..a20befa54 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -27,7 +27,6 @@ PR #277 is the canonical Result Application source/test parent and #233 is its p ## Documentation authority and convergence PR #324 is the canonical root architecture/CHANGELOG/product-gap documentation lane for this stack. It owns the Result Application naming explanation in `ARCHITECTURE.md`, `CHANGELOG.md`, `docs/doctoring/result-application-semantic-identifiers.md`, and this baseline; it must not regain production/test authority already owned by source PRs. - The lifecycle/outbox security lineage remains owned by #319 and its direct runtime-column authority child #336. Their relation-lock, catalog/role/program authority and final-column/`atttypmod` runtime parity remain source concerns until normal protected integration. Final documentation convergence must preserve both Result Application and lifecycle/outbox evidence after their source lineages legitimately integrate. Transient protected tips, branch heads, helper reconciliation identities, hosted-run IDs, review state, release inventory and queue state belong in the live integration ledger (#244) and their owning PRs. This document records durable ownership, protocol state, integration order and product gaps so normal branch/base movement does not immediately stale the product contract. @@ -38,7 +37,7 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Noema owner `.github#2079` owns finding↔confirmed-probe relation semantics and changed-location truncation behavior. Scheduler/RCA owner `.github#2170` owns the Required OpenCode coverage-RCA/full-suite dependency path. Review-sidecar owner `.github#1629` owns one-shot provider-default preflight admission without caller-authored provider/model/group preference, token/sampling values, inference retry budgets, paid fallback or duplicate shell inference. `.github#2094` retains the trusted `uv`/materializer repair. - The independent CodeQL deployment-order owner is `.github#2106`. Its durable contract is a backward-compatible versioned dispatch handler with one authenticated run-wide settlement owner, followed only after normal protected integration by `.github#2040` ordinary/non-force reconciliation and producer cutover. Canonical sequencing remains `#2106 normal protected integration -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm or protection bypass is accepted. + `.github#2106` is the normally integrated deployment-order/bootstrap lineage for the backward-compatible versioned CodeQL dispatch handler and its single authenticated run-wide settlement owner. The current combined successor `.github#2040` owns ordinary/non-force convergence and producer cutover on top of that protected authority. Canonical sequencing is now `#2106 integrated bootstrap lineage -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm or protection bypass is accepted. 2. **Lifecycle/outbox convergence.** #319 and direct child #336 remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and complete runtime-column/`atttypmod` parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. @@ -54,7 +53,7 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 8. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including complete column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. -9. **Provider-neutral review transport and immutable CO release.** `contextual-orchestrator` owns provider/model routing, timeout semantics and the released agent API/client/schema boundary. The multi-ready Noema timeout repair remains owned by `contextual-orchestrator#1176`; packaging prerequisite #995 and immutable-release owner #1030 must reach their own normal protected integration path before consumers can claim a released contract. Mutable branch heads, protected source SHAs, sidecar pins or branch-local GREEN are not release authority. +9. **Provider-neutral review transport and immutable CO release.** `contextual-orchestrator` owns provider/model routing, timeout semantics and the released agent API/client/schema boundary. The multi-ready Noema timeout repair remains owned by `contextual-orchestrator#1176`; release-mechanism lineage #1030 is normally integrated, and its current release-gate successor #1186 must converge on protected CO source before publication. Consumers may claim a released contract only after the live release successor reaches normal protected integration and an immutable CO GitHub Release actually exists. Mutable branch heads, protected source SHAs, sidecar pins or branch-local GREEN are not release authority. The required order is owner RED -> causal source repair -> exact-head GREEN -> protected integration -> version/CHANGELOG/tag/package -> exact-commit SBOM/provenance/reproducibility/rollback -> immutable Release -> thin consumer pin/canary. Central Actions model-backed workflows may consume only the released CO boundary through a gateway token and `orchestrator/free`; provider/model/group secrets or paid fallback remain CO-owned and must not be hard-coded in pg or central leaf workflows. @@ -63,7 +62,6 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 11. **Provider-neutral `BatchInferencePort` convergence.** Issue #318 remains the canonical architecture gap between pg's target provider-neutral ownership and the current direct OpenAI-compatible `/files` + `/batches` client implementation. The direct client is not itself the desired long-term provider/model/key authority. Provider/model discovery, routing/fallback and credential authority must move behind an explicit pg-owned port/ACL that consumes a released Contextual-Orchestrator API/client/schema; branch SHAs, copied CO source, hard-coded provider groups or direct provider credentials are not acceptable substitutes. #317 remains the live owner for the current `batch_api_client.py` surface and #347 separately owns its provider-resource-identifier primitive-authority defect. The migration in #318 must therefore preserve #347's security invariant rather than make it disappear by deleting or renaming the direct client: behavior-bearing caller identifiers must be rejected before they can become URL formatting, credential-resolution, transport-preparation, comparison, logging, persistence or evidence authority. Completion requires owner RED -> minimum causal repair -> exact-head GREEN -> normal protected integration -> immutable CO release -> pg consumer pin/canary, followed by removal or restriction of direct provider authority only after successor contract and adversarial evidence are complete. - 12. **Provider content retention, deletion and erasure authority.** Issue #136 remains a buyer-visible content-lifecycle gap even though protected product code already exposes bounded provider-file expiry inputs and explicit caller-authorized `delete_file()` primitives. Those primitives do not prove that every compatible provider accepts retention fields, that a terminal batch authorizes deletion, that already-deleted/not-found responses are reconciled correctly, or that transient/uncertain deletion failures can be treated as success. They also do not establish crash/restart-safe automatic cleanup, durable cleanup audit, local PostgreSQL retention/export/erasure, backup erasure, host-log erasure, cryptographic erasure or legal-erasure guarantees. Residual source work must remain serialized behind the active `batch_api_client.py` writer #317 until that owner reaches protected integration or a verified successor completely inherits its valid delta. Completion requires an explicit provider capability/compatibility contract, reviewed already-deleted/not-found and uncertain-failure reconciliation semantics, explicit deletion authority that is never inferred from lifecycle terminality alone, bounded content-free evidence that survives remote file disappearance, and strict separation of remote-provider retention from local PostgreSQL, backup, telemetry and host-storage authorities. #195/#196 retain repository-wide threat/data-governance ownership; #229/#321/#324 retain their existing canonical documentation surfaces rather than spawning a competing retention-doc writer. From dac2803ffb22277b144dbbc4bac8cce1abde4ad5 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 18 Sep 2026 03:08:09 +0900 Subject: [PATCH 45/57] docs(product): restore baseline paragraph separation --- docs/product-technical-gap-baseline.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index a20befa54..6c9fb8567 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -27,6 +27,7 @@ PR #277 is the canonical Result Application source/test parent and #233 is its p ## Documentation authority and convergence PR #324 is the canonical root architecture/CHANGELOG/product-gap documentation lane for this stack. It owns the Result Application naming explanation in `ARCHITECTURE.md`, `CHANGELOG.md`, `docs/doctoring/result-application-semantic-identifiers.md`, and this baseline; it must not regain production/test authority already owned by source PRs. + The lifecycle/outbox security lineage remains owned by #319 and its direct runtime-column authority child #336. Their relation-lock, catalog/role/program authority and final-column/`atttypmod` runtime parity remain source concerns until normal protected integration. Final documentation convergence must preserve both Result Application and lifecycle/outbox evidence after their source lineages legitimately integrate. Transient protected tips, branch heads, helper reconciliation identities, hosted-run IDs, review state, release inventory and queue state belong in the live integration ledger (#244) and their owning PRs. This document records durable ownership, protocol state, integration order and product gaps so normal branch/base movement does not immediately stale the product contract. @@ -62,6 +63,7 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 11. **Provider-neutral `BatchInferencePort` convergence.** Issue #318 remains the canonical architecture gap between pg's target provider-neutral ownership and the current direct OpenAI-compatible `/files` + `/batches` client implementation. The direct client is not itself the desired long-term provider/model/key authority. Provider/model discovery, routing/fallback and credential authority must move behind an explicit pg-owned port/ACL that consumes a released Contextual-Orchestrator API/client/schema; branch SHAs, copied CO source, hard-coded provider groups or direct provider credentials are not acceptable substitutes. #317 remains the live owner for the current `batch_api_client.py` surface and #347 separately owns its provider-resource-identifier primitive-authority defect. The migration in #318 must therefore preserve #347's security invariant rather than make it disappear by deleting or renaming the direct client: behavior-bearing caller identifiers must be rejected before they can become URL formatting, credential-resolution, transport-preparation, comparison, logging, persistence or evidence authority. Completion requires owner RED -> minimum causal repair -> exact-head GREEN -> normal protected integration -> immutable CO release -> pg consumer pin/canary, followed by removal or restriction of direct provider authority only after successor contract and adversarial evidence are complete. + 12. **Provider content retention, deletion and erasure authority.** Issue #136 remains a buyer-visible content-lifecycle gap even though protected product code already exposes bounded provider-file expiry inputs and explicit caller-authorized `delete_file()` primitives. Those primitives do not prove that every compatible provider accepts retention fields, that a terminal batch authorizes deletion, that already-deleted/not-found responses are reconciled correctly, or that transient/uncertain deletion failures can be treated as success. They also do not establish crash/restart-safe automatic cleanup, durable cleanup audit, local PostgreSQL retention/export/erasure, backup erasure, host-log erasure, cryptographic erasure or legal-erasure guarantees. Residual source work must remain serialized behind the active `batch_api_client.py` writer #317 until that owner reaches protected integration or a verified successor completely inherits its valid delta. Completion requires an explicit provider capability/compatibility contract, reviewed already-deleted/not-found and uncertain-failure reconciliation semantics, explicit deletion authority that is never inferred from lifecycle terminality alone, bounded content-free evidence that survives remote file disappearance, and strict separation of remote-provider retention from local PostgreSQL, backup, telemetry and host-storage authorities. #195/#196 retain repository-wide threat/data-governance ownership; #229/#321/#324 retain their existing canonical documentation surfaces rather than spawning a competing retention-doc writer. From c63892212102751f7c5763070a0201b1e38ffe3b Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 18 Sep 2026 08:06:06 +0900 Subject: [PATCH 46/57] docs(product): refresh CO release and FinOps gap authority --- docs/product-technical-gap-baseline.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 6c9fb8567..36ecaf6ba 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -54,7 +54,7 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 8. **Buyer latency envelope.** Issue #307 remains an acquisition gap. The applicable package-owned buyer path must measure p50/p95/p99 across connection acquisition, retained lock acquisition/wait, live relation/catalog/role/program authority admission including complete column/`atttypmod` checks, tenant binding, data I/O, cleanup, realistic cardinality/fanout, lock/I/O/connection pressure, saturation and failure. `p95 <= 20 ms` is an acceptance target, not a current product claim. #319/#336 own the relevant runtime/admission paths, so a competing benchmark source lane must not duplicate or bypass their source authority. -9. **Provider-neutral review transport and immutable CO release.** `contextual-orchestrator` owns provider/model routing, timeout semantics and the released agent API/client/schema boundary. The multi-ready Noema timeout repair remains owned by `contextual-orchestrator#1176`; release-mechanism lineage #1030 is normally integrated, and its current release-gate successor #1186 must converge on protected CO source before publication. Consumers may claim a released contract only after the live release successor reaches normal protected integration and an immutable CO GitHub Release actually exists. Mutable branch heads, protected source SHAs, sidecar pins or branch-local GREEN are not release authority. +9. **Provider-neutral review transport and immutable CO release.** `contextual-orchestrator` owns provider/model routing, timeout semantics and the released agent API/client/schema boundary. The multi-ready Noema timeout repair remains owned by `contextual-orchestrator#1176`; release-mechanism lineage #1030 and release-gate successor #1186 are now normally integrated into protected CO source. That integration makes immutable publication executable, but it is not itself a release: consumers may claim a released contract only after an actual immutable CO GitHub Release exists for an eligible protected source/version and its package, exact-commit SBOM, provenance, reproducibility and rollback evidence verify. Mutable branch heads, protected source SHAs, sidecar pins or branch-local GREEN are not release authority. The required order is owner RED -> causal source repair -> exact-head GREEN -> protected integration -> version/CHANGELOG/tag/package -> exact-commit SBOM/provenance/reproducibility/rollback -> immutable Release -> thin consumer pin/canary. Central Actions model-backed workflows may consume only the released CO boundary through a gateway token and `orchestrator/free`; provider/model/group secrets or paid fallback remain CO-owned and must not be hard-coded in pg or central leaf workflows. @@ -80,16 +80,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires auditable succession/recovery paths for repository administration and external release/security authorities, onboarding/offboarding and credential/key recovery without repository-embedded secrets, protected-branch and deterministic workflow controls that survive maintainer loss or turnover, and release/rollback authority explicitly separated from build evidence. Future reviewer/CODEOWNERS changes must be enabled only when real least-privilege independent human authority can satisfy them, with dry-run and rollback evidence; at least two humans is an acquisition objective rather than a fabricated prerequisite for today's central merge-policy repair. #306 owns the residual operational-continuity contract, `.github#772` owns central approval-policy satisfiability, and canonical governance prose remains with #229 while this baseline records only the buyer gap. -16. **FinOps usage completeness and cost-attribution evidence.** Issue #312 remains a buyer-visible acquisition gap because the existing bounded usage-evidence slice can distinguish provenance authority such as `LOCAL_MEASURED`, `PROVIDER_REPORTED`, `HOST_RATE_ESTIMATE`, and `RECONCILED`, while nullable token counts alone do not preserve every measurement-completeness state needed for auditable cost attribution. In particular, measured zero, provider-unavailable/unknown usage, estimated usage, and a reconciled aggregate containing estimated or unknown components must not collapse into the same representation or disappear from evidence merely because a bounded integer count is absent or available. +16. **FinOps usage completeness and cost-attribution evidence.** Issue #312 remains a buyer-visible acquisition gap, but the canonical #315 implementation lane now has a branch-local pg-owned measurement contract in addition to provenance authority. `UsageCompleteness` distinguishes `COMPLETE`, `PARTIAL`, `UNAVAILABLE`, and `MIXED`; measured zero remains distinct from unavailable usage; and lossy count/completeness combinations fail closed. That source is still candidate evidence until its exact head obtains the required repository/central acceptance, review and normal protected integration, so the product gap is not complete merely because the representation exists on a Draft branch. - Completion requires a realistic pg-domain RED proving which semantically distinct usage states the current evidence representation cannot preserve, followed by one explicit closed measurement/completeness contract or equivalent lossless representation rather than a mutable provider enum. The released Contextual-Orchestrator ACL in #318 must map upstream usage into that pg-owned contract without coercing unavailable/unknown usage to zero, silently dropping a completed call, or relabeling a mixed aggregate as authoritative measured usage. Evidence remains content-minimal: tenant scope and bounded opaque identifiers/counts/provenance may be retained, but prompts, results, JSONL/business content, provider bodies, credentials, provider/model routing policy, mutable price books and branch SHAs do not become FinOps authority. Pricing and billing settlement remain outside the current evidence primitive unless separately reviewed. Source widening stays on the canonical `usage_evidence.py` writer #315 or its deliberate ordinary/non-force successor after a fresh #316 writer census; this baseline records the buyer contract only and does not open a competing implementation lane. + Completion now requires preserving that orthogonal completeness/provenance split through protected integration and the released Contextual-Orchestrator ACL in #318: upstream unavailable/unknown usage must not be coerced to zero, completed calls must not disappear from evidence, and reconciled/mixed aggregates must not be relabeled as authoritative measured usage. The contract must remain pg-owned rather than mirror a mutable provider/CO enum. Evidence remains content-minimal: tenant scope and bounded opaque identifiers/counts/provenance/completeness may be retained, but prompts, results, JSONL/business content, provider bodies, credentials, provider/model routing policy, mutable price books and branch SHAs do not become FinOps authority. Pricing and billing settlement remain outside the current evidence primitive unless separately reviewed. Source changes stay on canonical `usage_evidence.py` writer #315 or its deliberate ordinary/non-force successor after a fresh #316 writer census; this baseline records the buyer contract only and does not open a competing implementation lane. ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. - -Long-running LLM/provider/model computation must occur outside an explicit PostgreSQL transaction and without holding avoidable database locks. A transaction may protect the minimal aggregate state transition before or after external work; it must not remain idle while waiting for remote inference or CPU/GPU computation. - -## Evidence status - -Open stack heads are authoritative only for their own branch-local evidence. Protected `main` is authoritative for integrated behavior, and immutable releases are authoritative for released-contract identity. Queued, cancelled, skipped, predecessor, branch-local or mechanically mergeable evidence is not promoted to protected or released truth. Live run-level statuses are maintained in #244 and the owning PRs; this baseline deliberately avoids treating a transient queue state as a durable product contract. \ No newline at end of file From a1d8a0ae92372be38012ddd23b02cc977eeb3a4a Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 08:06:21 +0900 Subject: [PATCH 47/57] docs(product): refresh central integration owner map --- docs/product-technical-gap-baseline.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 36ecaf6ba..db1fede8c 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -36,9 +36,9 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted 1. **Dependency-root and central review integration.** #233 remains the protected-integration dependency root. It is test-only and repository-local acceptance cannot substitute for the live central required-workflow path or qualifying independent approval. Protected `.github/main` is the integrated central workflow authority; exact owner heads, helper PRs, run IDs, review state and transient queue state must be read from #244 and the owning central PR immediately before mutation or merge. - Noema owner `.github#2079` owns finding↔confirmed-probe relation semantics and changed-location truncation behavior. Scheduler/RCA owner `.github#2170` owns the Required OpenCode coverage-RCA/full-suite dependency path. Review-sidecar owner `.github#1629` owns one-shot provider-default preflight admission without caller-authored provider/model/group preference, token/sampling values, inference retry budgets, paid fallback or duplicate shell inference. `.github#2094` retains the trusted `uv`/materializer repair. + Current durable central ownership is split by control-plane responsibility: `.github#2040` owns PR-review scheduler reconciliation and scheduler repository-identity admission; `.github#2268` owns generic queue-health owner/repository admission; `.github#2271` owns CodeQL `repository_dispatch` target admission; `.github#2269` and `.github#2272` own the SAST/authenticated GitHub-API request-hardening family, including redirect-credential containment and the reusable Pages shell-input boundary; `.github#1644` and `.github#772` own review-policy source/owner-plane reconciliation and structurally satisfiable solo-maintainer governance. Other model/review control-plane owners are resolved live from #244 rather than frozen here. - `.github#2106` is the normally integrated deployment-order/bootstrap lineage for the backward-compatible versioned CodeQL dispatch handler and its single authenticated run-wide settlement owner. The current combined successor `.github#2040` owns ordinary/non-force convergence and producer cutover on top of that protected authority. Canonical sequencing is now `#2106 integrated bootstrap lineage -> #2040 ordinary/non-force reconciliation/versioned cutover -> fresh exact-head terminal evidence -> unchanged consumer canary`. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm or protection bypass is accepted. + Valid sibling deltas are not disposable. #2269's authenticated redirect containment and focused regressions, #2272's Pages shell-boundary repair/regression, and the repaired admission slices in #2268/#2271 must be inherited or adopted path-wise by their canonical successors before an owner lane can retire. Canonical sequencing is central security/admission repair -> fresh exact-head terminal evidence -> ordinary/non-force #2040 reconciliation -> structurally satisfiable review governance -> fresh unchanged-head #233 evidence. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm, predecessor-evidence transfer or protection bypass is accepted. 2. **Lifecycle/outbox convergence.** #319 and direct child #336 remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and complete runtime-column/`atttypmod` parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. @@ -86,4 +86,4 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted ## Security / operability baseline -The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. +The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. \ No newline at end of file From 2aa369d6247e277534fdc8e462d8e6af81511696 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 12:02:02 +0900 Subject: [PATCH 48/57] docs(acquisition): add support lifecycle evidence gap --- docs/product-technical-gap-baseline.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index db1fede8c..64c5df860 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -84,6 +84,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion now requires preserving that orthogonal completeness/provenance split through protected integration and the released Contextual-Orchestrator ACL in #318: upstream unavailable/unknown usage must not be coerced to zero, completed calls must not disappear from evidence, and reconciled/mixed aggregates must not be relabeled as authoritative measured usage. The contract must remain pg-owned rather than mirror a mutable provider/CO enum. Evidence remains content-minimal: tenant scope and bounded opaque identifiers/counts/provenance/completeness may be retained, but prompts, results, JSONL/business content, provider bodies, credentials, provider/model routing policy, mutable price books and branch SHAs do not become FinOps authority. Pricing and billing settlement remain outside the current evidence primitive unless separately reviewed. Source changes stay on canonical `usage_evidence.py` writer #315 or its deliberate ordinary/non-force successor after a fresh #316 writer census; this baseline records the buyer contract only and does not open a competing implementation lane. +17. **Support lifecycle and vulnerability-response evidence.** Issue #309 remains a buyer-visible release/security-governance gap. Repository-level support and vulnerability-response statements must be bound to real released identities and an auditable response-state model rather than inferred from `main`, a version literal, branch-local GREEN, or an unpublished package candidate. Protected-main security-fix eligibility and customer-supported release identity are separate authorities; if no eligible immutable release exists, the supported-release set must resolve deterministically without inventing support authority. + + Completion requires #198's immutable release identity to define exactly when support starts, transitions to a successor, and ends; deterministic business-day/time-zone and event semantics for acknowledgement, triage, remediation-target and disclosure clocks; explicit severity and exception/escalation authority; confidential advisory handling that preserves low-cardinality audit evidence without exposing exploit material, reporter PII, credentials or arbitrary exception text; remediation bound to exact reviewed source and, where a released artifact is claimed fixed, to the same version/tag/package/container/SBOM/provenance identity; immutable history for state/severity/mitigation/disclosure/closure; and tested emergency mitigation/rollback that does not bypass protected-source or release gates. #306 separately owns maintainer/succession continuity. Moving release inventory, exact heads, clocks in flight and current governance state remain live evidence in #244 and the owning release/security surfaces rather than frozen into this baseline. + ## Security / operability baseline -The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. \ No newline at end of file +The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. From 04aff47b36eb14d7f6d205bed9273222d35281d1 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 13:03:26 +0900 Subject: [PATCH 49/57] docs(security): correct protected secret-encryption authority --- ARCHITECTURE.md | 11 ++++++++++- docs/product-technical-gap-baseline.md | 4 ++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 27a51b831..576c85fd9 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -3,11 +3,20 @@ ## Deployment boundary `pg-llm-batch` remains independently deployable and embeddable. PostgreSQL owns -configuration, encrypted secrets, token counting, JSONL payloads, and durable +configuration, secret storage, token counting, JSONL payloads, and durable provider lifecycle state. Provider HTTP behavior remains behind `BatchAPIClient`, while host services may inject credential, observation-order, and lifecycle-persistence seams without changing provider semantics. +Protected `SecretStore` does **not** make encryption-at-rest mandatory. A supplied +Fernet key encrypts stored values; without one, the current compatibility path +base64-obfuscates values unless the caller explicitly sets +`require_encryption=True`. Mandatory Fernet policy, migration of historical +unencrypted rows, key rotation/recovery, and external key-custody evidence remain +the buyer/security gap tracked by #121 and the active config/secret source owner. +Do not describe the protected product as encryption-required until that contract +is normally integrated and released. + ## Durable lifecycle tenancy `DurableBatchAPIClient` is the backward-compatible standalone facade. diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 64c5df860..1c9346b06 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -88,6 +88,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires #198's immutable release identity to define exactly when support starts, transitions to a successor, and ends; deterministic business-day/time-zone and event semantics for acknowledgement, triage, remediation-target and disclosure clocks; explicit severity and exception/escalation authority; confidential advisory handling that preserves low-cardinality audit evidence without exposing exploit material, reporter PII, credentials or arbitrary exception text; remediation bound to exact reviewed source and, where a released artifact is claimed fixed, to the same version/tag/package/container/SBOM/provenance identity; immutable history for state/severity/mitigation/disclosure/closure; and tested emergency mitigation/rollback that does not bypass protected-source or release gates. #306 separately owns maintainer/succession continuity. Moving release inventory, exact heads, clocks in flight and current governance state remain live evidence in #244 and the owning release/security surfaces rather than frozen into this baseline. +18. **Provider-secret encryption and custody lifecycle.** Issue #121 remains a buyer-visible confidentiality gap. Protected `SecretStore` encrypts values only when a Fernet key is supplied; without a key the compatibility path stores base64-obfuscated values unless the caller explicitly requires encryption. Therefore protected product documentation must not claim mandatory encryption-at-rest merely because encrypted operation is available. + + Completion requires the canonical config/secret source lineage to make valid Fernet authority mandatory before database access, remove reversible-obfuscation writes from production secret storage, authenticate persisted encryption-state/schema authority with least-privilege read/write access and no runtime DDL, and migrate recoverable historical unencrypted rows atomically without disclosing plaintext, ciphertext, keys, DSNs or lower-layer diagnostics. The remaining lifecycle must cover bounded key rotation/recovery and old-key retirement, restart/recovery/concurrency behavior, operator key-custody/recovery evidence, rollback, packaging/SBOM/provenance and immutable release binding. `com_config` and `com_secrets` remain deployment-global unless a separately reviewed product decision changes that contract. #210 (or its verified successor) owns source/schema implementation; #229 owns broad security/governance prose; #324 owns this root architecture/product-gap correction and does not acquire runtime authority. + ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. From a0877d25df5bf322728de0066cf6ae3b1534d2a3 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 14:01:34 +0900 Subject: [PATCH 50/57] docs(gaps): track permanent live PostgreSQL acceptance --- docs/product-technical-gap-baseline.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 1c9346b06..1ec9ba369 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -92,6 +92,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires the canonical config/secret source lineage to make valid Fernet authority mandatory before database access, remove reversible-obfuscation writes from production secret storage, authenticate persisted encryption-state/schema authority with least-privilege read/write access and no runtime DDL, and migrate recoverable historical unencrypted rows atomically without disclosing plaintext, ciphertext, keys, DSNs or lower-layer diagnostics. The remaining lifecycle must cover bounded key rotation/recovery and old-key retirement, restart/recovery/concurrency behavior, operator key-custody/recovery evidence, rollback, packaging/SBOM/provenance and immutable release binding. `com_config` and `com_secrets` remain deployment-global unless a separately reviewed product decision changes that contract. #210 (or its verified successor) owns source/schema implementation; #229 owns broad security/governance prose; #324 owns this root architecture/product-gap correction and does not acquire runtime authority. +19. **Permanent live PostgreSQL acceptance on exact PR heads.** Issue #340 remains a release-integrity gap because protected `main` still does not run the repository's complete real PostgreSQL integration suite as a permanent hosted acceptance lane. Draft #341 has already established branch-local reality evidence: a test-first workflow RED proved the missing `pytest -m integration` path, the enabled lane then exposed and repaired a real PostgreSQL fixture defect, and exact-head GREEN subsequently proved the complete live integration marker. A later #296 successor also passed a new realistic PostgreSQL recovery-readiness specimen through that same lane, showing that the workflow selects later database-semantic regressions rather than only its own fixture. + + Completion is still protected-integration work rather than another test invention. The canonical workflow must remain serialized through its live workflow-owner stack; on the final exact head it must check out the exact PR source, build the first-party PostgreSQL `with-tiktoken` fixture, create and mask ephemeral credentials, verify database and extension readiness, execute the complete integration marker without sample reduction or semantic skips, and tear down credential/container material under failure as well as success. Existing supported-Python, exact 100% owned production coverage/public-docstring, package/container and Release Acceptance gates remain additive rather than substitutes. After normal integration, a real successor carrying a database-semantic specimen must again materialize and execute the permanent lane from the exact protected ancestry. Branch-local #341/#296 GREEN is not protected-main acceptance or immutable release authority; #340 closes only after that integrated proof exists. + ## Security / operability baseline The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. From dceb13f7372159fa7e109b686399eaac5366c386 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 15:05:36 +0900 Subject: [PATCH 51/57] docs(recovery): bind PITR observer edge semantics --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 229eb171c..1383c02fc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Bounded read-only PostgreSQL PITR target-configuration observation on a caller-owned already-connected isolated recovery target. The observer reads exactly eight recovery-target settings plus `pg_is_in_recovery()`, uses bounded result materialization, fails closed on malformed, duplicate, oversized, pending-restart, inactive-recovery, or mismatched evidence, and returns content-free live observation provenance. It does not write recovery configuration, create `recovery.signal`, supply `restore_command`, prove WAL/archive/timeline completeness or target attainment, promote recovery, prove application readiness, or establish achieved RPO/RTO or DR capability. +- Bounded read-only PostgreSQL PITR target-configuration observation on a caller-owned already-connected isolated recovery target. The observer first snapshots the exact reviewed `PostgresPitrRecoveryTarget`; wrong-type authority or a target mutated out of that reviewed contract fails before cursor acquisition or database I/O. It reads exactly eight recovery-target settings plus `pg_is_in_recovery()`, uses bounded result materialization, and fails closed on malformed, duplicate, oversized, pending-restart, inactive-recovery, or mismatched evidence. When a reviewed `name` or `immediate` target intentionally has no inclusion edge, the effective `recovery_target_inclusive` setting must remain PostgreSQL 18's default `on`; time/XID/LSN targets retain their explicit reviewed inclusion edge. Returned provenance is content-free. The observer does not write recovery configuration, create `recovery.signal`, supply `restore_command`, prove WAL/archive/timeline completeness or target attainment, promote recovery, prove application readiness, or establish achieved RPO/RTO or DR capability. - Caller-owned physical/WAL/PITR recovery profile binder (`bind_postgres_physical_recovery_profile()` / `parse_postgres_physical_recovery_profile()`). The seam records method, From 4be995a381a54461d72f0a8f19a81e67ffedbdeb Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 16:03:51 +0900 Subject: [PATCH 52/57] docs(architecture): bound reconciliation scheduling authority --- ARCHITECTURE.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 576c85fd9..a3d98a8e4 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -64,6 +64,32 @@ Rollback to the former two-column key is unsafe until an operator proves that no The packaged schema and Docker initialization schema are maintained as exact mirrors and must be reapplied successfully more than once. +## Reconciliation orchestration boundary + +Protected `main` contains bounded reconciliation primitives, not a package-owned +automatic worker. `reconcile_batch_candidates()` executes one finite +scheduler-independent provider pass. Its protected contract explicitly leaves +candidate discovery, scheduling, tenant authorization, and any cross-process +lease to the host. Durable candidate discovery, PostgreSQL advisory single-flight, +and caller-owned result/checkpoint application are separate primitives; their +presence must not be described as an autonomous reconciliation service. + +Issue #102 remains the buyer/operability gap for composing those primitives into +a bounded automatic loop with crash/restart recovery, durable terminal-work +retirement, content-free operator evidence, and realistic high-cardinality +acceptance. A future loop must preserve minimal PostgreSQL transactions: reserve +or read the minimum durable state, commit or roll back before provider/model +network work or retry backoff, and open a new bounded transaction only for the +next durable transition. Session-advisory coordination remains transient and +must not be represented as a durable lease or as distributed exactly-once +delivery. + +The active reconciliation source slices remain separately owned by their +canonical PRs/issues, including candidate validation, bounded database result +materialization, sweep evidence, and Result Application. This documentation +records the protected capability boundary only; it does not transfer their +runtime/test authority into #324 or authorize a competing scheduler branch. + ## Logical restore execution `restore_postgres_logical_backup()` is a bounded direct-SQL restore seam. The From d41b61ce310bfd1a633bae265df5c5aa1da73325 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 18:31:16 +0900 Subject: [PATCH 53/57] docs(gap): record package version authority --- docs/product-technical-gap-baseline.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index 1ec9ba369..db607ca1d 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -96,6 +96,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion is still protected-integration work rather than another test invention. The canonical workflow must remain serialized through its live workflow-owner stack; on the final exact head it must check out the exact PR source, build the first-party PostgreSQL `with-tiktoken` fixture, create and mask ephemeral credentials, verify database and extension readiness, execute the complete integration marker without sample reduction or semantic skips, and tear down credential/container material under failure as well as success. Existing supported-Python, exact 100% owned production coverage/public-docstring, package/container and Release Acceptance gates remain additive rather than substitutes. After normal integration, a real successor carrying a database-semantic specimen must again materialize and execute the permanent lane from the exact protected ancestry. Branch-local #341/#296 GREEN is not protected-main acceptance or immutable release authority; #340 closes only after that integrated proof exists. +20. **Single package-version authority and immutable release identity.** Issue #109 remains a release-integrity gap because source/runtime/build version equality is still maintained by convention rather than one reviewed machine-readable authority, while no immutable repository release identity currently authorizes treating a source literal as shipped product truth. A future drift between build metadata, installed distribution metadata and `pg_llm_batch.__version__` would weaken provenance, rollback diagnosis and supportability even if ordinary tests remained green. + + Completion requires one deterministic version source from which source checkout, wheel/sdist metadata, installed distribution metadata, runtime/CLI version output, SBOM/provenance and release tag/version evidence are derived or cross-checked so they cannot disagree silently. Clean-archive and editable/development behavior must fail in a bounded actionable way when distribution metadata is unavailable; version bump and CHANGELOG/release acceptance must be dry-run testable without publishing; rollback to a prior release identity must be unambiguous. This is not authority to create a tag or release merely to close the issue. Source mutation remains serialized behind the then-live package/version writers, including #210 while it owns `pyproject.toml`/`uv.lock`; a fresh PR/ref census must prove the package/version surface writer-safe before #109 implementation begins. Moving heads, run IDs, tag/release inventory and writer leases remain in #244 and live owner PRs rather than this durable baseline. + ## Security / operability baseline -The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. +The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. \ No newline at end of file From 13965705e830f866c6e86a35d5df3a0e8a332f99 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 19:00:21 +0900 Subject: [PATCH 54/57] docs(product): record compatibility and deprecation buyer gap --- docs/product-technical-gap-baseline.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index db607ca1d..a59e406af 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -100,6 +100,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires one deterministic version source from which source checkout, wheel/sdist metadata, installed distribution metadata, runtime/CLI version output, SBOM/provenance and release tag/version evidence are derived or cross-checked so they cannot disagree silently. Clean-archive and editable/development behavior must fail in a bounded actionable way when distribution metadata is unavailable; version bump and CHANGELOG/release acceptance must be dry-run testable without publishing; rollback to a prior release identity must be unambiguous. This is not authority to create a tag or release merely to close the issue. Source mutation remains serialized behind the then-live package/version writers, including #210 while it owns `pyproject.toml`/`uv.lock`; a fresh PR/ref census must prove the package/version surface writer-safe before #109 implementation begins. Moving heads, run IDs, tag/release inventory and writer leases remain in #244 and live owner PRs rather than this durable baseline. +21. **Public compatibility and deprecation contract.** Issue #308 remains a buyer-visible API/acquisition gap because the repository states Semantic Versioning and exports an explicit package surface, but protected product truth still has no single machine-testable contract defining which Python/API/schema/CLI/evidence behaviors are compatibility promises, what constitutes a breaking change, how a deliberate deprecation progresses, or how those decisions bind to an immutable release. Issue #109 owns mechanical version-source authority; it does not define compatibility semantics. + + Completion requires one reviewed compatibility policy spanning top-level `__all__` and documented public Python entry points, CLI command/options and stable machine-readable output, durable PostgreSQL schema/evidence formats, and serialized public evidence objects while explicitly excluding private helpers, test seams, generated artifacts and implementation details. It must define package-specific `MAJOR`/`MINOR`/`PATCH` semantics including a deliberate pre-1.0 rule; classify removal/rename/signature/type/default/exception/serialized-field/CLI-output/durable-schema/privacy-authority changes; preserve a security fail-closed correction path without weakening unsafe behavior for compatibility; and define a bounded deprecation lifecycle with warning/evidence, migration alternative, earliest removal identity, support window and final-removal proof. Diagnostics remain content-free. Deterministic contract tests must detect unsupported public-surface, serialized, CLI and durable-schema drift without freezing incidental implementation detail; durable changes require migration plus rollback/recovery evidence. Compatibility decisions bind to exact source/package/version/CHANGELOG/SBOM/provenance/release identity through #109/#198, not to a branch-only GREEN. Embedding hosts retain caller-owned connection/provider/exporter authority while pg-owned public contracts remain versioned package authority. Implementation stays serialized behind the live package/export/version/CLI/schema/documentation writers identified by a fresh intended-path census; #229 retains canonical broad documentation ownership and #324 records only this durable buyer gap rather than opening a competing implementation lane. + ## Security / operability baseline -The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. \ No newline at end of file +The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. From aaa5fd4815da4eccd0c994ff4d54ab56119d3103 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 20:02:58 +0900 Subject: [PATCH 55/57] docs(product): record release manifest validation gap --- docs/product-technical-gap-baseline.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index a59e406af..e39e111c4 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -104,6 +104,10 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires one reviewed compatibility policy spanning top-level `__all__` and documented public Python entry points, CLI command/options and stable machine-readable output, durable PostgreSQL schema/evidence formats, and serialized public evidence objects while explicitly excluding private helpers, test seams, generated artifacts and implementation details. It must define package-specific `MAJOR`/`MINOR`/`PATCH` semantics including a deliberate pre-1.0 rule; classify removal/rename/signature/type/default/exception/serialized-field/CLI-output/durable-schema/privacy-authority changes; preserve a security fail-closed correction path without weakening unsafe behavior for compatibility; and define a bounded deprecation lifecycle with warning/evidence, migration alternative, earliest removal identity, support window and final-removal proof. Diagnostics remain content-free. Deterministic contract tests must detect unsupported public-surface, serialized, CLI and durable-schema drift without freezing incidental implementation detail; durable changes require migration plus rollback/recovery evidence. Compatibility decisions bind to exact source/package/version/CHANGELOG/SBOM/provenance/release identity through #109/#198, not to a branch-only GREEN. Embedding hosts retain caller-owned connection/provider/exporter authority while pg-owned public contracts remain versioned package authority. Implementation stays serialized behind the live package/export/version/CLI/schema/documentation writers identified by a fresh intended-path census; #229 retains canonical broad documentation ownership and #324 records only this durable buyer gap rather than opening a competing implementation lane. +22. **Canonical release-manifest semantic validation.** Issue #278 remains a release-integrity and provenance gap. `verify_reproducible_release(...)` constructs the package's bounded canonical manifest, but protected `write_release_manifest(...)` still accepts an arbitrary `Mapping[str, Any]`, materializes it, and serializes it before the package has established that the value is actually the canonical release-evidence schema. Descriptor-relative no-follow traversal, stable-parent checks, atomic replacement and fsync make file placement safer; they do not turn arbitrary caller-supplied JSON into trusted release evidence. + + Completion requires validation before filesystem mutation or caller-controlled container behavior can become authority: exact built-in container/primitive admission; the complete canonical key set with `schema_version == 1`; reuse of the existing distribution/version/source-commit/source-date grammar; exactly the canonical wheel and sdist artifact records with exact key sets, exact built-in filenames, lowercase 64-hex SHA-256 values and bounded exact integer sizes; rejection of missing, unknown, duplicate, ambiguous or oversized claims; deterministic canonical ordering/JSON; and preservation of the existing descriptor-bound no-follow, atomic-replace, cleanup and content-free error boundaries. This contract proves only the reproducibility evidence the package actually verifies; it does not manufacture signing, trusted-builder, attestation, SLSA-level, legal, CSAP, SOC 2 or certification authority. Source mutation stays frozen until a fresh complete open-PR plus no-PR ref changed-path census proves `pg_llm_batch/release_evidence.py` and its owning tests are writer-exclusive; #198/#200 remain the immutable release/release-acceptance authorities and no release is published merely to close #278. + ## Security / operability baseline -The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. +The architecture requires bounded provider response processing, exact tenant validation, parameterized transaction-local tenant context, forced RLS, non-superuser/non-`BYPASSRLS` application roles, controlled retries only where semantics permit, bounded package-owned snapshots and diagnostics, deterministic checkpoint conflict behavior, explicit connection cleanup, and descriptor-bound recovery/release evidence. Changes to these boundaries require dedicated RED/GREEN regressions and doctoring rather than being hidden inside naming or documentation refactors. \ No newline at end of file From 056025a870d3ea6630fbd52a1cff7b43eac1c30d Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Sat, 19 Sep 2026 22:02:21 +0900 Subject: [PATCH 56/57] docs(architecture): bound health diagnostic disclosure --- ARCHITECTURE.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index a3d98a8e4..2f3b5e194 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -90,6 +90,30 @@ materialization, sweep evidence, and Result Application. This documentation records the protected capability boundary only; it does not transfer their runtime/test authority into #324 or authorize a competing scheduler branch. +## Diagnostic disclosure boundary + +`check_health()` is an operator-facing diagnostic report, not a public-safe +serialization contract. Protected `main` currently preserves backend `detail` +values and maps a database failure to `detail=str(exc)`, so that internal report +can contain lower-layer PostgreSQL diagnostics. The HTTP `/healthz` path does +not expose that report directly: `serve_healthz()` passes it through +`public_health_report()`, which emits only the fixed required component names and +boolean readiness states. + +The standalone `health` CLI currently prints the unprojected `check_health()` +report. Its output must therefore be treated as operator-only and must not be +represented as safe for untrusted logs, tenant-visible telemetry, public HTTP, +or other user-facing surfaces. Issue #203 owns the remaining runtime hardening: +the CLI needs a bounded content-free projection or equally strict coded +diagnostic contract while preserving readiness exit semantics and useful +operator failure classification. DSNs, credentials, certificate/private-key +material, SQL text, provider content, arbitrary exception strings, and backend +connection diagnostics must not become public diagnostic evidence. + +This section records the protected capability boundary only. It does not move +`health.py` or CLI runtime/test authority into #324; source work for #203 still +requires the invocation-scoped writer/path census before mutation. + ## Logical restore execution `restore_postgres_logical_backup()` is a bounded direct-SQL restore seam. The From 782620982520fed46f6b6ef68c7320a61dbb311f Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Mon, 21 Sep 2026 22:02:52 +0900 Subject: [PATCH 57/57] docs(gaps): stop freezing central mutable owners --- docs/product-technical-gap-baseline.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/product-technical-gap-baseline.md b/docs/product-technical-gap-baseline.md index e39e111c4..b82fbeaee 100644 --- a/docs/product-technical-gap-baseline.md +++ b/docs/product-technical-gap-baseline.md @@ -34,11 +34,9 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted ## Current product / technical gaps -1. **Dependency-root and central review integration.** #233 remains the protected-integration dependency root. It is test-only and repository-local acceptance cannot substitute for the live central required-workflow path or qualifying independent approval. Protected `.github/main` is the integrated central workflow authority; exact owner heads, helper PRs, run IDs, review state and transient queue state must be read from #244 and the owning central PR immediately before mutation or merge. +1. **Dependency-root and central review integration.** #233 remains the protected-integration dependency root. It is test-only and repository-local acceptance cannot substitute for the live central required-workflow path or qualifying independent approval. Protected `.github/main` is the integrated central workflow authority; exact owner PR numbers, heads, helper/successor identities, run IDs, review state and transient queue state must be read from #244 and the live central owner immediately before mutation or merge rather than frozen into this durable baseline. - Current durable central ownership is split by control-plane responsibility: `.github#2040` owns PR-review scheduler reconciliation and scheduler repository-identity admission; `.github#2268` owns generic queue-health owner/repository admission; `.github#2271` owns CodeQL `repository_dispatch` target admission; `.github#2269` and `.github#2272` own the SAST/authenticated GitHub-API request-hardening family, including redirect-credential containment and the reusable Pages shell-input boundary; `.github#1644` and `.github#772` own review-policy source/owner-plane reconciliation and structurally satisfiable solo-maintainer governance. Other model/review control-plane owners are resolved live from #244 rather than frozen here. - - Valid sibling deltas are not disposable. #2269's authenticated redirect containment and focused regressions, #2272's Pages shell-boundary repair/regression, and the repaired admission slices in #2268/#2271 must be inherited or adopted path-wise by their canonical successors before an owner lane can retire. Canonical sequencing is central security/admission repair -> fresh exact-head terminal evidence -> ordinary/non-force #2040 reconciliation -> structurally satisfiable review governance -> fresh unchanged-head #233 evidence. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm, predecessor-evidence transfer or protection bypass is accepted. + Durable responsibility stays split by control-plane concern rather than by a specific mutable PR identity: central `.github` owns required-workflow scheduling and repository admission, queue/admission diagnosis, CodeQL/review dispatch and target validation, authenticated GitHub-API and reusable-workflow security, review-policy reconciliation, and structurally satisfiable independent-review governance. A valid delta in any of those concerns must be integrated by its then-live canonical owner or completely inherited by a verified successor before the older lane retires. Canonical sequencing is central security/admission repair -> fresh exact-head terminal evidence -> ordinary/non-force owner reconciliation -> structurally satisfiable review governance -> fresh unchanged-head #233 evidence. No pg-side copied workflow, synthetic status, source-neutral freshness commit, manual rerun storm, predecessor-evidence transfer or protection bypass is accepted. 2. **Lifecycle/outbox convergence.** #319 and direct child #336 remain a separate security/runtime source lineage. Their relation-lock, catalog/role/program authority and complete runtime-column/`atttypmod` parity must converge non-destructively with Result Application before a single integrated release claim can be made. Long-running calculation/model work must not hold an explicit PostgreSQL transaction or database lock while external computation is idle; aggregate transactions remain minimal and database state transitions are separated from long-running LLM/provider work. @@ -76,9 +74,9 @@ Transient protected tips, branch heads, helper reconciliation identities, hosted Completion requires deterministic heartbeat/non-starvation RED evidence, an explicit async resolver contract or a bounded compatibility adapter for synchronous resolvers, bounded worker/connection fan-out, a finite credential-resolution cancellation/resource policy distinct from provider HTTP timeout, deterministic cleanup, and realistic concurrent failure/restart evidence. Endpoint alias and gateway URL authority must be validated before credential-bearing provider I/O, diagnostics must not leak secret/URL/DSN/provider content, and plaintext caching must not become an indefinite shortcut. Credential database work may use its own minimal bounded transaction, but no `BEGIN`, row/relation lock or transaction-scoped advisory lock may survive into provider/model/network execution. Source work remains serialized until a fresh intended-path census proves the active provider-client and config/secret writers have normally integrated, been completely inherited by a canonical successor, or are independently non-overlapping; #111 must also preserve #122's package-wide database wait envelope and #318's released Contextual-Orchestrator authority rather than hard-coding provider/model/group policy. -15. **Maintainer succession and governance continuity.** Issue #306 remains a buyer-visible operational-continuity gap. Central `.github#772` owns making the live approval policy structurally satisfiable without self-approval, fictional reviewers, bot-as-human treatment, routine administrator bypass or deterministic-gate weakening; that central policy repair is necessary but does not by itself remove the repository's residual single-person operational dependency across administration, security response, release publication, rollback/recovery, emergency access and acquisition handover. +15. **Maintainer succession and governance continuity.** Issue #306 remains a buyer-visible operational-continuity gap. Central approval-policy ownership is resolved live through #244 rather than frozen to a mutable `.github` PR number here. That central policy repair must make the live approval policy structurally satisfiable without self-approval, fictional reviewers, bot-as-human treatment, routine administrator bypass or deterministic-gate weakening; it is necessary but does not by itself remove the repository's residual single-person operational dependency across administration, security response, release publication, rollback/recovery, emergency access and acquisition handover. - Completion requires auditable succession/recovery paths for repository administration and external release/security authorities, onboarding/offboarding and credential/key recovery without repository-embedded secrets, protected-branch and deterministic workflow controls that survive maintainer loss or turnover, and release/rollback authority explicitly separated from build evidence. Future reviewer/CODEOWNERS changes must be enabled only when real least-privilege independent human authority can satisfy them, with dry-run and rollback evidence; at least two humans is an acquisition objective rather than a fabricated prerequisite for today's central merge-policy repair. #306 owns the residual operational-continuity contract, `.github#772` owns central approval-policy satisfiability, and canonical governance prose remains with #229 while this baseline records only the buyer gap. + Completion requires auditable succession/recovery paths for repository administration and external release/security authorities, onboarding/offboarding and credential/key recovery without repository-embedded secrets, protected-branch and deterministic workflow controls that survive maintainer loss or turnover, and release/rollback authority explicitly separated from build evidence. Future reviewer/CODEOWNERS changes must be enabled only when real least-privilege independent human authority can satisfy them, with dry-run and rollback evidence; at least two humans is an acquisition objective rather than a fabricated prerequisite for today's central merge-policy repair. #306 owns the residual operational-continuity contract, central `.github` owns approval-policy satisfiability, and canonical governance prose remains with #229 while this baseline records only the buyer gap. 16. **FinOps usage completeness and cost-attribution evidence.** Issue #312 remains a buyer-visible acquisition gap, but the canonical #315 implementation lane now has a branch-local pg-owned measurement contract in addition to provenance authority. `UsageCompleteness` distinguishes `COMPLETE`, `PARTIAL`, `UNAVAILABLE`, and `MIXED`; measured zero remains distinct from unavailable usage; and lossy count/completeness combinations fail closed. That source is still candidate evidence until its exact head obtains the required repository/central acceptance, review and normal protected integration, so the product gap is not complete merely because the representation exists on a Draft branch.