matrx-orm 3.1.257__tar.gz → 3.1.259__tar.gz

{matrx_orm-3.1.257 → matrx_orm-3.1.259}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.257
+Version: 3.1.259
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current

matrx_orm-3.1.259/docs/attachment-concurrency.md

@@ -0,0 +1,28 @@
+---
+type: Reference
+title: Credential attachment concurrency verification
+description: Real-router race probe for parent-held attachment mutation and byte materialization.
+---
+
+# Credential attachment concurrency verification
+
+Use the real Vault router and auth provider as `admin@admin.com`, with an
+isolated agent-owned session and a new item stamped with this run's `test_run_id`.
+Never reuse another run's item or touch the owner's credentials.
+
+1. Pause an attachment request after it takes the parent lock but before its
+   child write. Release it first: it must return 201. The following item delete
+   must return 204, and a fresh router list must have no live child.
+2. Reverse the schedule: pause the attachment request before parent-lock
+   acquisition, complete the item delete, then release the request. It must
+   refuse and leave no live child.
+3. Repeat both schedules with download and trusted resolve paused before byte
+   materialization. No child bytes may escape after the winning deletion.
+4. Remove each run-owned disposable item through the canonical cascade, archive
+   retained run-owned fixtures and independently verify no live test records
+   remain. End and verify rejection of the owned session; close only this run's
+   browser/process resources and clear any owned clipboard content.
+
+This probe complements the focused serialization guards; offline source tests do
+not establish live concurrency acceptance. Pending product acceptance belongs in
+the [Vault register](../../../common-docs/projects/credential-sharing-browser-login/REGISTER.md).

matrx_orm-3.1.259/docs/index.md

@@ -0,0 +1,10 @@
+---
+type: Reference
+title: matrx-orm verification and migration guides
+description: Focused package operating guides.
+---
+
+# Package guides
+
+- [Migrations](migrations.md)
+- [Credential attachment concurrency verification](attachment-concurrency.md)

{matrx_orm-3.1.257 → matrx_orm-3.1.259}/matrx_orm/secrets_battery/FEATURE.md

@@ -1,6 +1,6 @@
 # matrx-orm secrets battery — the ONE credential vault
 
-> Cross-repo plan (implementation authority): `/Users/armanisadeghi/code/common-docs/systems/account/vault-secrets/FEATURE.md` — read it before expanding credential storage or package resolution in any repository. Phase 1 (schema) + Phase 2 (this battery's item layer, rotation script, unified aidream service) are live.
+> Cross-repo plan (implementation authority): `/Users/armanisadeghi/code/common-docs/systems/account/vault-secrets/FEATURE.md` — read it before expanding credential storage or package resolution in any repository.
 
 **One table, one key, everywhere.** Every platform credential — personal AND
 organizational — lives in `users.user_secrets` (Fernet-encrypted). Every package
@@ -40,9 +40,8 @@ Installed migration 1047 requires exact keys, typed identifiers and timestamp,
 locked original ownership, and exactly one manifest and one changed component
 bound to the locked active personal password field. Organization-owned history refuses until the host supplies the
 grant/offboarding parent-lock contract. Capture, list/reveal, and restore are
-backend capabilities for this bounded personal-password chain. Migration 1166
-is reviewed and enabled in source; installed behavior requires the migration
-ledger and exact live validator bodies. The physical history timestamp remains
+backend capabilities for this bounded personal-password chain. The physical
+history timestamp remains
 the destination audit time, while authenticated backup source dates are retained
 separately when the installed contract supports them.
 
@@ -82,7 +81,7 @@ ownership/shape helper and does not decrypt.
 
 **Native source admission (`native_source.py`).** `validate_native_source` is the server reader of the provider's exact source-v1 byte format; Rust remains the encoder and authenticator. It requires an explicit positive source-size limit, preserves nullable names and bytes, rejects duplicate/noncanonical JSON and COSE, and derives public metadata only after maintained P-256 key-pair validation. The result is provider-custody data, never a response model or generic field. `repr` and fixed failures omit material. `scripts/check_native_source_parity.py --rust-core <native-vault-provider/core>` compares the real compiled Rust reader against the server corpus; no mocked oracle. This prerequisite adds no creator, materializer, database row or native readiness.
 
-**Native lifecycle component (`native_lifecycle.py`).** The shared coordinator must supply locked parent/child projections from the exported field constants, current host management authority and its active transaction. Inspection locks the exact native metadata child; component delete/restore mutate only that child's tombstone and lifecycle. Deletion accepts active and restored-quarantined sources; recovery compares aware ISO manifest timestamps to database timestamps, then parses the already-validated manifest instant only at the typed native restore mutation boundary. Personal metadata provenance is enforced by the database guard, never inferred from the request scope. The item delete/restore coordinator invokes these operations for exact v2 native manifests, preserves auxiliary components and replay identity, and restores inactive quarantine. Actual aggregate database acceptance is UNVERIFIABLE here; it requires a current database-backed delete/restore/replay journey, tracked in the register. Contract: [native lifecycle](../../../../common-docs/projects/credential-sharing-browser-login/REGISTER.md).
+**Native lifecycle component (`native_lifecycle.py`).** The shared coordinator must supply locked parent/child projections from the exported field constants, current host management authority and its active transaction. Inspection locks the exact native metadata child; component delete/restore mutate only that child's tombstone and lifecycle. Deletion accepts active and restored-quarantined sources; recovery compares aware ISO manifest timestamps to database timestamps, then parses the already-validated manifest instant only at the typed native restore mutation boundary. Personal metadata provenance is enforced by the database guard, never inferred from the request scope. The item delete/restore coordinator invokes these operations for exact v2 native manifests, preserves auxiliary components and replay identity, and restores inactive quarantine. Contract: [native lifecycle](../../../../common-docs/projects/credential-sharing-browser-login/REGISTER.md).
 
 **`inject_into_sandbox=true` REQUIRES an env alias — refused otherwise.** A
 container environment is a NAME→value map, so a field with `key IS NULL` has
@@ -98,8 +97,7 @@ alone, each loud:
 2. **Resolution scream** — `_keyed_for_sandbox` logs an ERROR naming the row ids
    and skips them, so anything that got in around layer 1 is visible.
 3. **DB CHECK** `user_secrets_sandbox_injection_needs_key` (migration 0265) makes
-   the state unrepresentable; the column default moved `true` → `false` so the
-   database stops manufacturing violations on keyless inserts.
+   the state unrepresentable. The column default is `false`.
 
 Item surface: `create_credential_item` · `create_credential_bundle` (item + N
 fields, ONE transaction) · `get/list/update/delete_credential_item` (delete =
@@ -111,7 +109,7 @@ soft, atomic across item + fields + grants) · `add_credential_field` ·
 · `set_item_grants` · `list_granted_credential_items` ·
 `transfer_credential_item` (owner flip, no value copy, references survive) ·
 `fork_credential_item` (independent copy) · `resolve_legacy_env_key` (compat
-read that SCREAMS in logs until call sites migrate to stable references).
+read that SCREAMS in logs for legacy env-key access).
 
 Attachment surface (`attachments.py`): add/list/get/update metadata/replace/
 soft-delete; `reveal_credential_attachment` is the audited human download and
@@ -136,16 +134,7 @@ parent-delete helper deliberately takes no second parent lock because its caller
 already owns it; fork still locks its source parent and copies only its stable
 snapshot.
 
-**Live race recipe (requires an explicitly authorized disposable admin item).**
-Through the real Vault router and auth provider, create an admin-owned item and
-pause the attachment request after it takes its parent lock but before its child
-write. Releasing it first must return 201; the following item delete returns
-204 and a fresh router list has no live child. In the inverse ordering, complete
-the delete first and then release the attachment request: it must be refused
-and must not leave a live child. Repeat with download and trusted resolve paused
-before byte materialization. Remove the disposable item through the canonical
-cascade after each run. This is a live concurrency probe, never a replacement
-for the focused unit guards.
+Verification: [attachment concurrency probe](../../docs/attachment-concurrency.md).
 
 **Grants: use the single-grant operations.** `add_item_grant` /
 `update_item_grant` / `remove_item_grant` change ONE recipient and leave the
@@ -179,7 +168,9 @@ make it "easier to read".
 **Restored native enablement (`native_enable.py`).** The primitive requires an
 active transaction and one exact restored v2 aggregate; it changes only parent
 status and protected-source activity. The host owns current scope, authority,
-grant locks and audit.
+grant locks and audit. Personal passkey metadata must retain a non-null creation
+organization independent of the audit request organization; organization-owned
+aggregates still require parent, source and metadata organization equality.
 
 ## Mutation receipt routing
 
@@ -297,16 +288,11 @@ aidream's authorization layer is
 membership → `iam.has_org_access_for`, adminhood → `public.is_org_admin_for`,
 asserted before the battery is touched.
 
-### 🚨 "Assert first" is now MECHANICAL for sealed writes (`host_authorization.py`)
+### Sealed-write authorization (`host_authorization.py`)
 
-`add_credential_field` copies its owner columns **from the item**, so a host that
-writes first and authorizes second plants an attacker-chosen secret on a
-victim's item — and the row is already committed when the later check refuses.
-
-The battery still refuses to judge the decision — it refuses to be **the place
-where nobody made one**. Adding a `handling='sealed'` field to an EXISTING item
-requires the host to have RECORDED its decision for that `(item, actor)`,
-carrying `manage`:
+Adding a `handling='sealed'` field to an existing item requires the host to record
+a `manage` decision for `(item, actor)` before writing. The battery enforces the
+recorded decision without deciding tenancy.
 
 ```python
 from matrx_orm.secrets_battery import host_authorization, note_host_authorization
@@ -347,8 +333,7 @@ tenancy. Guard: `tests/test_secret_audit_names_its_organization.py`.
 - **Standalone package/service:** register your DB with matrx-orm, call the same
   `configure_secrets`. Key comes from `CREDENTIALS_ENCRYPTION_KEY` env, or pass
   `encryption_key=` (host injection).
-- Key resolution (byte-identical to the historical aidream implementation — all
-  existing ciphertexts keep decrypting): explicit key → `CREDENTIALS_ENCRYPTION_KEY`
+- Key resolution: explicit key → `CREDENTIALS_ENCRYPTION_KEY`
   (44-char urlsafe-base64 used directly, else SHA-256-derived) → `SUPABASE_SECRET_KEY`
   derivation with a loud warning → loud RuntimeError.
 
@@ -383,20 +368,13 @@ contributed org copies show `out_of_sync` afterward (cosmetic).
   (`totp_seed`, extend via `register_non_transferable_field_key`) are retired —
   soft-deleted, deactivated, audited — inside the transfer transaction, and are
   never copied by a fork; `TransferResult.fields_not_transferred` names them so
-  the confirmation can say the seed did not travel (D-15). 🚨 This is
+  the confirmation can say the seed did not travel. This is
   deliberately NOT "every sealed field": a sealed OAuth refresh token exists to
   move with the item it authenticates, and retiring those would break live
   integrations silently.
-- 🚨 **The `last_used_at` stamp on a bulk resolve locks rows in PRIMARY-KEY
-  ORDER.** `resolve_org_secrets` passes `lock_rows_in_pk_order=True`, and that is
-  load-bearing. This is the platform's hottest fan-out write: EVERY AI generation
-  folds the active organization's vault into its context
-  (aidream `ai_task.py` → `hydrate_context_secrets`), so N parallel agent
-  invocations in one workflow step run the same multi-row UPDATE over the same
-  rows at the same instant. Without a pinned lock order two of them take the same
-  locks in opposite orders and Postgres kills one (40P01). Never drop the flag
-  "because the ids are already sorted":
-  the PLAN decides lock order, not the array
+- Bulk `last_used_at` updates use `lock_rows_in_pk_order=True` to prevent
+  deadlocks between concurrent resolvers. Preserve this flag: SQL execution plans
+  determine lock order even when input IDs are sorted
   (`matrx_orm/query/FEATURE.md` § A multi-row UPDATE can pin its lock ORDER).
 - Every read is scoped by a **required** `user_id` or `organization_id`. No None
   = "show everything".
@@ -414,8 +392,3 @@ contributed org copies show `out_of_sync` afterward (cosmetic).
 Drift guard: `scripts/validate_secrets_decrypt.py` (loud, non-blocking, in
 `release.sh`) asserts every active field and attachment still decrypts with the
 configured key.
-
-Verified against live code + the live `users.user_secrets` /
-`users.credential_items` schema 2026-08-20 (destination-login metadata update,
-bundle create, reveal, sealed denial, editable gate, rotate, item grants, soft
-delete).

{matrx_orm-3.1.257 → matrx_orm-3.1.259}/matrx_orm/secrets_battery/native_enable.py

@@ -175,7 +175,7 @@ def _validate_auxiliaries(
             _fail("native passkey aggregate has an unrecorded live attachment")
 
 
-def _validate_ownership(parent: Mapping[str, Any], source: Mapping[str, Any], metadata: Mapping[str, Any], expected_organization_id: str) -> None:
+def _validate_ownership(parent: Mapping[str, Any], source: Mapping[str, Any], metadata: Mapping[str, Any]) -> None:
     user_id, organization_id = parent.get("user_id"), parent.get("organization_id")
     if (user_id is None) == (organization_id is None):
         _fail("native passkey parent ownership is invalid")
@@ -184,14 +184,18 @@ def _validate_ownership(parent: Mapping[str, Any], source: Mapping[str, Any], me
     if organization_id is not None:
         if source.get("user_id") is not None or not _same_id(source.get("organization_id"), organization_id) or not _same_id(metadata.get("organization_id"), organization_id):
             _fail("native passkey organization ownership does not match")
-    elif source.get("organization_id") is not None or not _same_id(source.get("user_id"), user_id) or not _same_id(metadata.get("organization_id"), expected_organization_id):
+    elif (
+        source.get("organization_id") is not None
+        or not _same_id(source.get("user_id"), user_id)
+        or metadata.get("organization_id") is None
+    ):
         _fail("native passkey personal ownership does not match")
 
 
 def _validate_locked_aggregate(
     parent: Mapping[str, Any], fields: Sequence[Mapping[str, Any]], attachments: Sequence[Mapping[str, Any]],
     metadata_rows: Sequence[Mapping[str, Any]],
-    deletion_id: str, expected_organization_id: str,
+    deletion_id: str,
 ) -> tuple[str, str, bool]:
     _require_keys(parent, NATIVE_ENABLE_PARENT_FIELDS, "parent")
     for field in fields:
@@ -219,7 +223,7 @@ def _validate_locked_aggregate(
         or not _same_id(metadata.get("source_field_id"), source.get("id"))
     ):
         _fail("native passkey restored aggregate shape is invalid")
-    _validate_ownership(parent, source, metadata, expected_organization_id)
+    _validate_ownership(parent, source, metadata)
     manifest_field_ids, manifest_attachment_ids = _validate_manifest(
         parent, deletion_id, source_id, passkey_id
     )
@@ -250,7 +254,7 @@ async def enable_native_passkey(
     await require_host_authorization(parent_id, actor_id, capability=CAPABILITY_MANAGE,
                                      operation="native_passkey_enable", audit_organization_id=audit_organization_id)
     source_id, _passkey_id, already_enabled = _validate_locked_aggregate(
-        parent, fields, attachments, metadata_rows, deletion_id, audit_organization_id
+        parent, fields, attachments, metadata_rows, deletion_id
     )
     if already_enabled:
         return True

{matrx_orm-3.1.257 → matrx_orm-3.1.259}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.257"
+version = "3.1.259"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }

{matrx_orm-3.1.257 → matrx_orm-3.1.259}/tests/test_native_enable.py

@@ -227,20 +227,72 @@ async def test_historical_tombstoned_auxiliaries_outside_manifest_do_not_block_r
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("metadata_org", ["org", "wrong-personal-org"])
-async def test_personal_enable_binds_locked_personal_scope(_primitive_boundary, metadata_org):
+async def test_personal_enable_preserves_creation_provenance_across_audit_scope(_primitive_boundary):
     parent, fields, metadata = _aggregate()
     parent.update(user_id="actor", organization_id=None)
     fields[0].update(user_id="actor", organization_id=None)
-    metadata[0]["organization_id"] = metadata_org
-    async def run():
-        return await native_enable.enable_native_passkey(
+    metadata[0]["organization_id"] = "org-b"
+    assert await native_enable.enable_native_passkey(
+        parent, fields, [], metadata, deletion_id=DELETION,
+        actor_id="actor", audit_organization_id="org-a",
+    ) is False
+    # Persistence seam proves enablement cannot rewrite creation provenance.
+    assert metadata[0]["organization_id"] == "org-b"
+    assert "organization_id" not in repr(_primitive_boundary[0].calls + _primitive_boundary[1].calls)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("breakage", ["missing_owner", "source_owner", "missing_provenance", "org_source"])
+async def test_personal_enable_refuses_broken_owner_or_provenance(_primitive_boundary, breakage):
+    parent, fields, metadata = _aggregate()
+    parent.update(user_id="actor", organization_id=None)
+    fields[0].update(user_id="actor", organization_id=None)
+    metadata[0]["organization_id"] = "org-b"
+    if breakage == "missing_owner":
+        parent["user_id"] = None
+    elif breakage == "source_owner":
+        fields[0]["user_id"] = "other"
+    elif breakage == "missing_provenance":
+        metadata[0]["organization_id"] = None
+    else:
+        fields[0]["organization_id"] = "org-b"
+    with pytest.raises(CredentialRestoreConflictError):
+        await native_enable.enable_native_passkey(
+            parent, fields, [], metadata, deletion_id=DELETION,
+            actor_id="actor", audit_organization_id="org-a",
+        )
+    assert _primitive_boundary[0].calls == _primitive_boundary[1].calls == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("breakage", ["source_org", "metadata_org"])
+async def test_organization_enable_retains_exact_owner_equality(_primitive_boundary, breakage):
+    parent, fields, metadata = _aggregate()
+    if breakage == "source_org":
+        fields[0]["organization_id"] = "other-org"
+    else:
+        metadata[0]["organization_id"] = None
+    with pytest.raises(CredentialRestoreConflictError):
+        await native_enable.enable_native_passkey(
             parent, fields, [], metadata, deletion_id=DELETION,
             actor_id="actor", audit_organization_id="org",
         )
-    if metadata_org == "org":
-        assert await run() is False
+    assert _primitive_boundary[0].calls == _primitive_boundary[1].calls == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("breakage", ["source_parent", "metadata_parent", "metadata_source"])
+async def test_enable_refuses_wrong_native_component_linkage(_primitive_boundary, breakage):
+    parent, fields, metadata = _aggregate()
+    if breakage == "source_parent":
+        fields[0]["credential_item_id"] = "00000000-0000-4000-8000-000000000099"
+    elif breakage == "metadata_parent":
+        metadata[0]["credential_item_id"] = "00000000-0000-4000-8000-000000000099"
     else:
-        with pytest.raises(CredentialRestoreConflictError):
-            await run()
-        assert _primitive_boundary[0].calls == _primitive_boundary[1].calls == []
+        metadata[0]["source_field_id"] = "00000000-0000-4000-8000-000000000099"
+    with pytest.raises(CredentialRestoreConflictError):
+        await native_enable.enable_native_passkey(
+            parent, fields, [], metadata, deletion_id=DELETION,
+            actor_id="actor", audit_organization_id="org",
+        )
+    assert _primitive_boundary[0].calls == _primitive_boundary[1].calls == []