feat(core): portable org identity — locally-minted org_id, stamped on tenant-scoped rows (ACE-056/057)

[vishalkalbi27]

Goal

Give every self-hosted deployment a permanent, locally-minted, globally-unique org_id (uuid4) — minted once at agami-connect, persisted in org.yaml, and stamped on every tenant-scoped row. Today every deployment stamps the shared constant "local", so lifting one into the paid hosted product can't tell deployments apart. This makes the data portable so it imports as exactly one clean tenant.

agami-core stays single-tenant (N=1) — this is an identity seam, not multi-tenancy. Implements F14 (specs ACE-056 + ACE-057).

No-egress (the governing invariant)

The id is a local uuid4() plus a local file write — never transmitted. It travels only the day the operator exports their own DB. tests/test_privacy_no_network.py stays green (uuid4 / Path.write_text aren't network primitives).

ACE-056 — mint + resolve

• Organization.org_id (Optional) — required because the model is extra="forbid()"; the default keeps pre-F14 org.yaml loadable.
• build.ensure_org_id() — idempotent + deployment-scoped: keeps an existing id, else adopts a sibling profile's (so multi-datasource stays ONE tenant), else mints. write_tree() is the single mint chokepoint, so introspect/curate/snapshot all preserve it.
• loader.load_org_id() / deployment_org_id() — read-only, never raise on a missing/legacy file.
• tools.resolved_org_id() — AGAMI_ORG_ID → org.yaml → "local". The same resolver backs the deploy stamp (model_deploy._default_org) and the serve path, so writes and reads can't disagree. mcp_http logs the resolved id and its source.

Resolution scans the artifacts dir (not one "active" profile) — otherwise a container with AGAMI_PROFILE unset and the model under a named profile would silently resolve "local".

ACE-057 — stamp + backfill

• 012_users_org_id.sql — adds org_id to users (indexed non-PK; users is keyed by id/username, deliberately unlike the serving tables). feedback stays excluded (paid/AH surface, ACE-034).
• Backfill in model_deploy after migrations — UPDATE-moves legacy 'local' rows onto the minted id rather than re-seeding, because the redeploy DELETE is (org_id, datasource)-scoped and would otherwise orphan them; runtime tables are append-only and only fixable this way. No-op when the resolved id is still 'local'; idempotent on re-run. A static .sql can't do this (SQLite has no uuid function).

Verification

• uv run dev.py check — 1527 passed, ruff + gitleaks clean.
• uv run dev.py cover — 100% patch coverage (0 missing lines).
• Real end-to-end: /agami-connect minted org_id into org.yaml, and model_deploy stamped that exact uuid onto the serving rows in Postgres — no 'local' rows left.
• New tests/test_org_identity_e2e.py asserts mint-once immutability, deployment-scoped adoption, the deploy↔serve agreement invariant, and the legacy→local path.

Compatibility note (follow-up, not this PR)

Running the hosted repo's suite against this branch surfaced one cross-test issue: resolved_org_id() is memoized with a zero-arg lru_cache, so a consumer's tests can observe a stale org when they vary AGAMI_ORG_ID/artifacts dir in-process. Production is unaffected (env is fixed per process), and hosted's multi-tenant path never reaches it (the per-request contextvar short-circuits). Tracking separately rather than widening this PR.

Out of scope

• Multi-tenant isolation / runtime org-awareness (stays N=1).
• The hosted import/lift (AH F5 / AH-011).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements a “portable org identity” seam for single-tenant OSS deployments by minting a locally-generated org_id (uuid4 hex), persisting it in org.yaml, resolving it consistently at deploy/serve time, and stamping/backfilling tenant-scoped DB rows to prevent cross-deployment collisions during hosted lift/import.

Changes:

• Add Organization.org_id (optional) and mint/adopt/persist it via build.ensure_org_id() + write_tree(), with read-only resolution via loader.load_org_id() / deployment_org_id() and tools.resolved_org_id().
• Stamp/backfill DB rows from legacy 'local' to the resolved minted org id at deploy time; add org_id to users via migration 012_users_org_id.sql.
• Add/extend end-to-end tests to assert mint-once immutability, deployment-scoped adoption, deploy↔serve agreement, and backfill/credential-resolution invariants.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_schema.py	Asserts users.org_id exists, is NOT NULL with default 'local', and is indexed.
tests/test_org_identity_e2e.py	New E2E coverage for mint/adopt/resolve invariants and credential-resolution regression guard.
tests/test_org_cache.py	Adds resolver tests and isolates AGAMI_ARTIFACTS_DIR/cache behavior.
tests/test_model_deploy.py	Verifies deploy stamps minted org id and backfill updates legacy 'local' rows idempotently.
tests/conftest.py	Clears resolved_org_id LRU cache between tests to avoid env/artifacts-dir leakage.
plugins/agami/skills/agami-connect/SKILL.md	Updates connect skill docs to mint org_id for the sample copy path.
packages/agami-core/src/tools.py	Introduces resolved_org_id() + _credential_org_id() and routes execute_sql credential selection through the sentinel mapping.
packages/agami-core/src/semantic_model/models.py	Adds optional Organization.org_id field for backwards-compatible loads.
packages/agami-core/src/semantic_model/loader.py	Adds load_org_id() and deployment_org_id() to resolve minted ids without building full models.
packages/agami-core/src/semantic_model/cli.py	Adds sm ensure-org-id command to mint/persist org_id for models written outside introspect/curate.
packages/agami-core/src/semantic_model/build.py	Adds ensure_org_id() and stamps org_id into org.yaml via the main write chokepoint.
packages/agami-core/src/model_deploy.py	Uses unified resolver for deploy stamp and adds _backfill_org_id() executed after migrations.
packages/agami-core/src/migrations/core/012_users_org_id.sql	Adds users.org_id with default 'local' and an org index for tenant scoping.
packages/agami-core/src/mcp_http.py	Uses the unified resolver for the single-tenant org and logs resolved org_id + source.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[vishalkalbi27]

Checked this — the graceful failure you're describing is already in place, so no change here.

_read_yaml does open the file unguarded, so it raises FileNotFoundError. But cli.main() has a purpose-built handler for exactly that case (cli.py:1332-1339):

except FileNotFoundError as e:
    if "org.yaml" in str(e):
        _print_json({"error": "no_model", "detail": str(e)})
        return 3     # "no model here — run agami-connect"

Verified:

$ sm ensure-org-id /tmp/dir-with-no-org-yaml
{ "error": "no_model", "detail": "[Errno 2] No such file or directory: '.../org.yaml'" }
exit code: 3

That's a clear error and a non-zero exit, using the repo's established convention (exit 3 = "no model", distinct from 1 = validation and 2 = usage) shared by every other sm subcommand. Adding a local guard would make ensure-org-id report this condition differently from its siblings, which is the opposite of what we want.

[vishalkalbi27]

Good catch — valid, and fixed in 722f211.

The docstring described the earlier design (a per-profile load_org_id read) while the implementation resolves via loader.deployment_org_id across the whole artifacts dir. It also contradicted the inline comment four lines below it.

Worth more than a tidy-up, for the reason you gave: it documented precisely the behaviour we deliberately moved away from. resolve_profile() falls back to the literal "default" whenever AGAMI_PROFILE is unset and there's no .config — exactly a deploy container, whose model lives under its datasource's name (e.g. /artifacts/northpeak_salesforce/). A per-profile read would look for /artifacts/default/org.yaml, find nothing, resolve "local", and make the feature inert on the very deployments it exists for. Someone reading the old docstring could have "corrected" the code straight back into that bug.

The docstring now states the scan and why it's deployment-scoped (every profile in a dir carries the same id, so any of them answers the question). Also corrected "one org.yaml read per process" → "one artifacts-dir scan per process".