b3-prosaic-harness-postgres 0.2.1__tar.gz → 0.3.0__tar.gz

{b3_prosaic_harness_postgres-0.2.1/src/b3_prosaic_harness_postgres.egg-info → b3_prosaic_harness_postgres-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: b3-prosaic-harness-postgres
-Version: 0.2.1
-Summary: Explicit PostgreSQL run storage for Prosaic Harness
+Version: 0.3.0
+Summary: Explicit PostgreSQL run and conversation storage for Prosaic Harness
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: b3-prosaic-harness<0.8,>=0.7
+Requires-Dist: b3-prosaic-harness<0.9,>=0.8
 Requires-Dist: psycopg[binary]<4,>=3.2.3
 Requires-Dist: psycopg-pool<4,>=3.2
 Provides-Extra: test
@@ -24,11 +24,11 @@ Run on worker A, inspect/resume on worker B, without a shared writable run
 directory. Core remains database-free; install this separate adapter only when
 you need shared durable state. The API is synchronous; a private I/O thread
 bounds network waits. Model execution holds no database connection/transaction.
-The current candidate is `b3-prosaic-harness-postgres` **0.2.0**, selecting
-`b3-prosaic-harness>=0.7,<0.8`. The adapter is maintained in this repository but
+The conversation candidate is `b3-prosaic-harness-postgres` **0.3.0**, selecting
+`b3-prosaic-harness>=0.8,<0.9`. The adapter is maintained in this repository but
 installed and versioned separately, keeping PostgreSQL drivers optional for
 Harness users. Imports and CLI names remain unchanged. Final qualification and
-publication of the b3 release train are pending. The historical
+publication of this conversation release train are pending. The historical
 [Harness v0.6.1 release](https://github.com/B3Cognition/prosaic-harness/releases/tag/v0.6.1)
 retains its original 0.6.1/0.1.1 package names and receipts.
 
@@ -49,7 +49,7 @@ prosaic-harness-postgres --help
 
 ALWAYS migrate using a fresh environment or image; NEVER install legacy and b3
 distributions together because they own the same import paths. See
-[package migration](../../docs/package-migration.md). The Runtime 0.8 candidate
+[package migration](../../docs/package-migration.md). The Runtime 0.9 candidate
 must be available before this installation can resolve.
 
 Harness does **not** provision PostgreSQL, create databases/users, start a
@@ -220,3 +220,99 @@ session capacity atomically under the existing store mutex. A registering lease
 can no longer be counted twice while maintenance is scheduled. The database
 storage/fencing contract is unchanged. A unit scheduling-boundary regression and
 an owned PostgreSQL 16/18 race regression cover the transition.
+
+## Optional conversation sessions
+
+The conversation candidate adds `PostgresSessionStore` to this same optional
+distribution. It implements the public Harness `SessionStore` contract and uses
+the independent, logged `prosaic_harness_conversations` schema, storage version 1.
+Existing `PostgresRunStore` tables, grants and CLI `init`/`doctor` behavior remain
+compatible; those CLI commands continue to address workflow storage.
+
+Initialize conversation storage once with the schema owner's credentials:
+
+```python
+from prosaic_harness_postgres import PostgresSessionStore
+
+with PostgresSessionStore.from_env(
+    'HARNESS_MIGRATION_DSN', namespace='my-chat'
+) as owner:
+    owner.initialize()
+```
+
+Apply these grants as the owner, replacing `chat_runtime` with the existing
+application role. Role, database and secret creation remain operator tasks.
+
+```sql
+GRANT USAGE ON SCHEMA prosaic_harness_conversations TO chat_runtime;
+GRANT SELECT ON prosaic_harness_conversations.schema_version,
+    prosaic_harness_conversations.leases,
+    prosaic_harness_conversations.sessions,
+    prosaic_harness_conversations.receipts TO chat_runtime;
+GRANT INSERT, UPDATE ON prosaic_harness_conversations.leases,
+    prosaic_harness_conversations.sessions TO chat_runtime;
+GRANT INSERT ON prosaic_harness_conversations.receipts TO chat_runtime;
+```
+
+The runtime role needs no schema CREATE, schema-version UPDATE, receipt UPDATE
+or DELETE. A role with only workflow grants can continue using `PostgresRunStore`
+and cannot use conversation storage until it receives the separate grants.
+Conversation readiness rejects forbidden effective grants on non-owner runtime
+roles, including inherited and column-only grants. It also rejects schema-version
+INSERT/DELETE and table DELETE/TRUNCATE privileges. Revoke accidental extra
+permissions before accepting work.
+
+Schema owners and roles that immediately inherit schema-owner privileges remain
+administrative credentials: `initialize()` and operator `check_ready()` can
+validate their installation. Those checks cannot make an owner a restricted
+role. ALWAYS configure worker processes with separate non-owner runtime
+credentials and verify their ownership/grants; NEVER use migration credentials
+as the application's runtime DSN.
+Readiness performs no migration or fallback:
+
+```python
+from prosaic_harness import Conversation, ConversationScope
+from prosaic_harness_postgres import PostgresSessionStore
+
+scope = ConversationScope('my-chat', 'production', 'my-service', tenant, actor)
+with PostgresSessionStore.from_env(
+    'HARNESS_RUNTIME_DSN', namespace=scope.namespace
+) as sessions:
+    sessions.check_ready()
+    chat = Conversation(approved_bindings, store=sessions, scope=scope)
+    created = chat.create()
+```
+
+Derive `tenant`, `actor` and any billing account from current authenticated host
+state before each public operation. Scope ownership filters every session and
+receipt read; leases, revisions and writes also bind to the exact scope and
+address. A foreign owner sees `session_not_found`. The SQL role can still access
+its granted tables directly: namespaces and scope hashes do not replace host
+authorization or database row-level security.
+
+Use the same sealed bindings and logical workspace/journal identities on every
+worker. The default bounded pools and lease timings documented above apply.
+Each operation checks the writable primary and WAL settings, acquires a short
+transaction, then returns its connection. A conversation's model, tool and
+linked workflow execution holds no transaction or checked-out connection.
+Database generations fence late writes after ownership changes; they cannot
+cancel an external effect already in progress.
+
+Snapshots and immutable receipts use the common finite canonical UTF-8 session
+codec, with at most 8 MiB each. Their addresses and receipts are checked against
+allocated attempts, dispatch markers and the frozen scope/binding/input/context.
+Exact receipt repeats are idempotent under a live lease; conflicts fail without
+overwriting evidence. A lost COMMIT acknowledgement raises `store_unavailable`
+with `outcome_unknown` and invalidates the lease. Recover by reading authoritative
+state with fresh ownership; never blindly repeat inference or business effects.
+
+The session policy bounds retained/reserved logical records. PostgreSQL indexes,
+WAL, tool journals, replicas and backups add physical storage. The host must also
+enforce retained-session quotas and own any explicit retention/deletion policy;
+this adapter never automatically expires or deletes records.
+
+The required adapter suite includes both the existing workflow backend and the
+conversation backend. Run the owned PostgreSQL 16 and 18 fixtures shown above
+with `--require-postgres`. Missing infrastructure or any skipped required case
+fails qualification. Installed Linux AMD64 and ARM64 acceptance is required
+before claiming the conversation candidate is ready for production.

{b3_prosaic_harness_postgres-0.2.1 → b3_prosaic_harness_postgres-0.3.0}/README.md

@@ -4,11 +4,11 @@ Run on worker A, inspect/resume on worker B, without a shared writable run
 directory. Core remains database-free; install this separate adapter only when
 you need shared durable state. The API is synchronous; a private I/O thread
 bounds network waits. Model execution holds no database connection/transaction.
-The current candidate is `b3-prosaic-harness-postgres` **0.2.0**, selecting
-`b3-prosaic-harness>=0.7,<0.8`. The adapter is maintained in this repository but
+The conversation candidate is `b3-prosaic-harness-postgres` **0.3.0**, selecting
+`b3-prosaic-harness>=0.8,<0.9`. The adapter is maintained in this repository but
 installed and versioned separately, keeping PostgreSQL drivers optional for
 Harness users. Imports and CLI names remain unchanged. Final qualification and
-publication of the b3 release train are pending. The historical
+publication of this conversation release train are pending. The historical
 [Harness v0.6.1 release](https://github.com/B3Cognition/prosaic-harness/releases/tag/v0.6.1)
 retains its original 0.6.1/0.1.1 package names and receipts.
 
@@ -29,7 +29,7 @@ prosaic-harness-postgres --help
 
 ALWAYS migrate using a fresh environment or image; NEVER install legacy and b3
 distributions together because they own the same import paths. See
-[package migration](../../docs/package-migration.md). The Runtime 0.8 candidate
+[package migration](../../docs/package-migration.md). The Runtime 0.9 candidate
 must be available before this installation can resolve.
 
 Harness does **not** provision PostgreSQL, create databases/users, start a
@@ -200,3 +200,99 @@ session capacity atomically under the existing store mutex. A registering lease
 can no longer be counted twice while maintenance is scheduled. The database
 storage/fencing contract is unchanged. A unit scheduling-boundary regression and
 an owned PostgreSQL 16/18 race regression cover the transition.
+
+## Optional conversation sessions
+
+The conversation candidate adds `PostgresSessionStore` to this same optional
+distribution. It implements the public Harness `SessionStore` contract and uses
+the independent, logged `prosaic_harness_conversations` schema, storage version 1.
+Existing `PostgresRunStore` tables, grants and CLI `init`/`doctor` behavior remain
+compatible; those CLI commands continue to address workflow storage.
+
+Initialize conversation storage once with the schema owner's credentials:
+
+```python
+from prosaic_harness_postgres import PostgresSessionStore
+
+with PostgresSessionStore.from_env(
+    'HARNESS_MIGRATION_DSN', namespace='my-chat'
+) as owner:
+    owner.initialize()
+```
+
+Apply these grants as the owner, replacing `chat_runtime` with the existing
+application role. Role, database and secret creation remain operator tasks.
+
+```sql
+GRANT USAGE ON SCHEMA prosaic_harness_conversations TO chat_runtime;
+GRANT SELECT ON prosaic_harness_conversations.schema_version,
+    prosaic_harness_conversations.leases,
+    prosaic_harness_conversations.sessions,
+    prosaic_harness_conversations.receipts TO chat_runtime;
+GRANT INSERT, UPDATE ON prosaic_harness_conversations.leases,
+    prosaic_harness_conversations.sessions TO chat_runtime;
+GRANT INSERT ON prosaic_harness_conversations.receipts TO chat_runtime;
+```
+
+The runtime role needs no schema CREATE, schema-version UPDATE, receipt UPDATE
+or DELETE. A role with only workflow grants can continue using `PostgresRunStore`
+and cannot use conversation storage until it receives the separate grants.
+Conversation readiness rejects forbidden effective grants on non-owner runtime
+roles, including inherited and column-only grants. It also rejects schema-version
+INSERT/DELETE and table DELETE/TRUNCATE privileges. Revoke accidental extra
+permissions before accepting work.
+
+Schema owners and roles that immediately inherit schema-owner privileges remain
+administrative credentials: `initialize()` and operator `check_ready()` can
+validate their installation. Those checks cannot make an owner a restricted
+role. ALWAYS configure worker processes with separate non-owner runtime
+credentials and verify their ownership/grants; NEVER use migration credentials
+as the application's runtime DSN.
+Readiness performs no migration or fallback:
+
+```python
+from prosaic_harness import Conversation, ConversationScope
+from prosaic_harness_postgres import PostgresSessionStore
+
+scope = ConversationScope('my-chat', 'production', 'my-service', tenant, actor)
+with PostgresSessionStore.from_env(
+    'HARNESS_RUNTIME_DSN', namespace=scope.namespace
+) as sessions:
+    sessions.check_ready()
+    chat = Conversation(approved_bindings, store=sessions, scope=scope)
+    created = chat.create()
+```
+
+Derive `tenant`, `actor` and any billing account from current authenticated host
+state before each public operation. Scope ownership filters every session and
+receipt read; leases, revisions and writes also bind to the exact scope and
+address. A foreign owner sees `session_not_found`. The SQL role can still access
+its granted tables directly: namespaces and scope hashes do not replace host
+authorization or database row-level security.
+
+Use the same sealed bindings and logical workspace/journal identities on every
+worker. The default bounded pools and lease timings documented above apply.
+Each operation checks the writable primary and WAL settings, acquires a short
+transaction, then returns its connection. A conversation's model, tool and
+linked workflow execution holds no transaction or checked-out connection.
+Database generations fence late writes after ownership changes; they cannot
+cancel an external effect already in progress.
+
+Snapshots and immutable receipts use the common finite canonical UTF-8 session
+codec, with at most 8 MiB each. Their addresses and receipts are checked against
+allocated attempts, dispatch markers and the frozen scope/binding/input/context.
+Exact receipt repeats are idempotent under a live lease; conflicts fail without
+overwriting evidence. A lost COMMIT acknowledgement raises `store_unavailable`
+with `outcome_unknown` and invalidates the lease. Recover by reading authoritative
+state with fresh ownership; never blindly repeat inference or business effects.
+
+The session policy bounds retained/reserved logical records. PostgreSQL indexes,
+WAL, tool journals, replicas and backups add physical storage. The host must also
+enforce retained-session quotas and own any explicit retention/deletion policy;
+this adapter never automatically expires or deletes records.
+
+The required adapter suite includes both the existing workflow backend and the
+conversation backend. Run the owned PostgreSQL 16 and 18 fixtures shown above
+with `--require-postgres`. Missing infrastructure or any skipped required case
+fails qualification. Installed Linux AMD64 and ARM64 acceptance is required
+before claiming the conversation candidate is ready for production.

{b3_prosaic_harness_postgres-0.2.1 → b3_prosaic_harness_postgres-0.3.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "b3-prosaic-harness-postgres"
-version = "0.2.1"
-description = "Explicit PostgreSQL run storage for Prosaic Harness"
+version = "0.3.0"
+description = "Explicit PostgreSQL run and conversation storage for Prosaic Harness"
 requires-python = ">=3.11"
 readme = "README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE", "NOTICE"]
-dependencies = ["b3-prosaic-harness>=0.7,<0.8", "psycopg[binary]>=3.2.3,<4", "psycopg-pool>=3.2,<4"]
+dependencies = ["b3-prosaic-harness>=0.8,<0.9", "psycopg[binary]>=3.2.3,<4", "psycopg-pool>=3.2,<4"]
 
 [project.optional-dependencies]
 test = ["pytest>=8", "build>=1", "setuptools>=77", "wheel", "packaging"]

{b3_prosaic_harness_postgres-0.2.1 → b3_prosaic_harness_postgres-0.3.0/src/b3_prosaic_harness_postgres.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: b3-prosaic-harness-postgres
-Version: 0.2.1
-Summary: Explicit PostgreSQL run storage for Prosaic Harness
+Version: 0.3.0
+Summary: Explicit PostgreSQL run and conversation storage for Prosaic Harness
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 License-File: NOTICE
-Requires-Dist: b3-prosaic-harness<0.8,>=0.7
+Requires-Dist: b3-prosaic-harness<0.9,>=0.8
 Requires-Dist: psycopg[binary]<4,>=3.2.3
 Requires-Dist: psycopg-pool<4,>=3.2
 Provides-Extra: test
@@ -24,11 +24,11 @@ Run on worker A, inspect/resume on worker B, without a shared writable run
 directory. Core remains database-free; install this separate adapter only when
 you need shared durable state. The API is synchronous; a private I/O thread
 bounds network waits. Model execution holds no database connection/transaction.
-The current candidate is `b3-prosaic-harness-postgres` **0.2.0**, selecting
-`b3-prosaic-harness>=0.7,<0.8`. The adapter is maintained in this repository but
+The conversation candidate is `b3-prosaic-harness-postgres` **0.3.0**, selecting
+`b3-prosaic-harness>=0.8,<0.9`. The adapter is maintained in this repository but
 installed and versioned separately, keeping PostgreSQL drivers optional for
 Harness users. Imports and CLI names remain unchanged. Final qualification and
-publication of the b3 release train are pending. The historical
+publication of this conversation release train are pending. The historical
 [Harness v0.6.1 release](https://github.com/B3Cognition/prosaic-harness/releases/tag/v0.6.1)
 retains its original 0.6.1/0.1.1 package names and receipts.
 
@@ -49,7 +49,7 @@ prosaic-harness-postgres --help
 
 ALWAYS migrate using a fresh environment or image; NEVER install legacy and b3
 distributions together because they own the same import paths. See
-[package migration](../../docs/package-migration.md). The Runtime 0.8 candidate
+[package migration](../../docs/package-migration.md). The Runtime 0.9 candidate
 must be available before this installation can resolve.
 
 Harness does **not** provision PostgreSQL, create databases/users, start a
@@ -220,3 +220,99 @@ session capacity atomically under the existing store mutex. A registering lease
 can no longer be counted twice while maintenance is scheduled. The database
 storage/fencing contract is unchanged. A unit scheduling-boundary regression and
 an owned PostgreSQL 16/18 race regression cover the transition.
+
+## Optional conversation sessions
+
+The conversation candidate adds `PostgresSessionStore` to this same optional
+distribution. It implements the public Harness `SessionStore` contract and uses
+the independent, logged `prosaic_harness_conversations` schema, storage version 1.
+Existing `PostgresRunStore` tables, grants and CLI `init`/`doctor` behavior remain
+compatible; those CLI commands continue to address workflow storage.
+
+Initialize conversation storage once with the schema owner's credentials:
+
+```python
+from prosaic_harness_postgres import PostgresSessionStore
+
+with PostgresSessionStore.from_env(
+    'HARNESS_MIGRATION_DSN', namespace='my-chat'
+) as owner:
+    owner.initialize()
+```
+
+Apply these grants as the owner, replacing `chat_runtime` with the existing
+application role. Role, database and secret creation remain operator tasks.
+
+```sql
+GRANT USAGE ON SCHEMA prosaic_harness_conversations TO chat_runtime;
+GRANT SELECT ON prosaic_harness_conversations.schema_version,
+    prosaic_harness_conversations.leases,
+    prosaic_harness_conversations.sessions,
+    prosaic_harness_conversations.receipts TO chat_runtime;
+GRANT INSERT, UPDATE ON prosaic_harness_conversations.leases,
+    prosaic_harness_conversations.sessions TO chat_runtime;
+GRANT INSERT ON prosaic_harness_conversations.receipts TO chat_runtime;
+```
+
+The runtime role needs no schema CREATE, schema-version UPDATE, receipt UPDATE
+or DELETE. A role with only workflow grants can continue using `PostgresRunStore`
+and cannot use conversation storage until it receives the separate grants.
+Conversation readiness rejects forbidden effective grants on non-owner runtime
+roles, including inherited and column-only grants. It also rejects schema-version
+INSERT/DELETE and table DELETE/TRUNCATE privileges. Revoke accidental extra
+permissions before accepting work.
+
+Schema owners and roles that immediately inherit schema-owner privileges remain
+administrative credentials: `initialize()` and operator `check_ready()` can
+validate their installation. Those checks cannot make an owner a restricted
+role. ALWAYS configure worker processes with separate non-owner runtime
+credentials and verify their ownership/grants; NEVER use migration credentials
+as the application's runtime DSN.
+Readiness performs no migration or fallback:
+
+```python
+from prosaic_harness import Conversation, ConversationScope
+from prosaic_harness_postgres import PostgresSessionStore
+
+scope = ConversationScope('my-chat', 'production', 'my-service', tenant, actor)
+with PostgresSessionStore.from_env(
+    'HARNESS_RUNTIME_DSN', namespace=scope.namespace
+) as sessions:
+    sessions.check_ready()
+    chat = Conversation(approved_bindings, store=sessions, scope=scope)
+    created = chat.create()
+```
+
+Derive `tenant`, `actor` and any billing account from current authenticated host
+state before each public operation. Scope ownership filters every session and
+receipt read; leases, revisions and writes also bind to the exact scope and
+address. A foreign owner sees `session_not_found`. The SQL role can still access
+its granted tables directly: namespaces and scope hashes do not replace host
+authorization or database row-level security.
+
+Use the same sealed bindings and logical workspace/journal identities on every
+worker. The default bounded pools and lease timings documented above apply.
+Each operation checks the writable primary and WAL settings, acquires a short
+transaction, then returns its connection. A conversation's model, tool and
+linked workflow execution holds no transaction or checked-out connection.
+Database generations fence late writes after ownership changes; they cannot
+cancel an external effect already in progress.
+
+Snapshots and immutable receipts use the common finite canonical UTF-8 session
+codec, with at most 8 MiB each. Their addresses and receipts are checked against
+allocated attempts, dispatch markers and the frozen scope/binding/input/context.
+Exact receipt repeats are idempotent under a live lease; conflicts fail without
+overwriting evidence. A lost COMMIT acknowledgement raises `store_unavailable`
+with `outcome_unknown` and invalidates the lease. Recover by reading authoritative
+state with fresh ownership; never blindly repeat inference or business effects.
+
+The session policy bounds retained/reserved logical records. PostgreSQL indexes,
+WAL, tool journals, replicas and backups add physical storage. The host must also
+enforce retained-session quotas and own any explicit retention/deletion policy;
+this adapter never automatically expires or deletes records.
+
+The required adapter suite includes both the existing workflow backend and the
+conversation backend. Run the owned PostgreSQL 16 and 18 fixtures shown above
+with `--require-postgres`. Missing infrastructure or any skipped required case
+fails qualification. Installed Linux AMD64 and ARM64 acceptance is required
+before claiming the conversation candidate is ready for production.

{b3_prosaic_harness_postgres-0.2.1 → b3_prosaic_harness_postgres-0.3.0}/src/b3_prosaic_harness_postgres.egg-info/SOURCES.txt

@@ -13,6 +13,9 @@ src/prosaic_harness_postgres/__init__.py
 src/prosaic_harness_postgres/cli.py
 src/prosaic_harness_postgres/leases.py
 src/prosaic_harness_postgres/schema.py
+src/prosaic_harness_postgres/session_leases.py
+src/prosaic_harness_postgres/session_schema.py
+src/prosaic_harness_postgres/session_store.py
 src/prosaic_harness_postgres/store.py
 src/prosaic_harness_postgres/transport.py
 tests/conftest.py
@@ -28,11 +31,18 @@ tests/test_recovery.py
 tests/test_registration.py
 tests/test_routing.py
 tests/test_schema.py
+tests/test_session_fencing.py
+tests/test_session_recovery.py
+tests/test_session_schema.py
+tests/test_session_store.py
+tests/test_session_workers.py
 tests/test_store.py
 tests/test_transport.py
 tests/test_workers.py
 tests/support/linux_wheel_smoke.py
 tests/support/local_cluster.py
 tests/support/model_server.py
+tests/support/session_documents.py
+tests/support/session_workers.py
 tests/support/tcp_proxy.py
 tests/support/workers.py

{b3_prosaic_harness_postgres-0.2.1 → b3_prosaic_harness_postgres-0.3.0}/src/b3_prosaic_harness_postgres.egg-info/requires.txt

@@ -1,4 +1,4 @@
-b3-prosaic-harness<0.8,>=0.7
+b3-prosaic-harness<0.9,>=0.8
 psycopg[binary]<4,>=3.2.3
 psycopg-pool<4,>=3.2
 

b3_prosaic_harness_postgres-0.3.0/src/prosaic_harness_postgres/__init__.py

@@ -0,0 +1,7 @@
+"""Separate PostgreSQL adapter for Prosaic Harness."""
+__version__ = '0.3.0'
+
+from .store import PostgresRunStore
+from .session_store import PostgresSessionStore
+
+__all__ = ['PostgresRunStore', 'PostgresSessionStore']

b3_prosaic_harness_postgres-0.3.0/src/prosaic_harness_postgres/session_leases.py

@@ -0,0 +1,10 @@
+"""Scoped conversation leases use the existing bounded renewal lifecycle."""
+from .leases import PostgresLease
+
+
+class PostgresSessionLease(PostgresLease):
+    def __init__(self, store, session_id, scope_content, scope_identity, started):
+        super().__init__(store, session_id, started)
+        self.session_id = session_id
+        self.scope_content = scope_content
+        self.scope_identity = scope_identity