legion-data 1.8.5 → 1.8.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b825eb46e0228251730ce4c339e76eac14c67e3001d1554495bf7f72ec0f5d0c
-  data.tar.gz: a9f797bd628944c509ea230003a927e5bf3ba434a08a50bdd6a35a34d719d72e
+  metadata.gz: edd18502b1d95a3863975b1144fa9b53cbc1a51d6306f20d2e02cb6b316d488c
+  data.tar.gz: eae1da697b4296e99898852da936a7247791e39e11e2d70fa0d64403e02145d6
 SHA512:
-  metadata.gz: 1d46e826a98465155b373512068ae0edc3caf29dd5a0b39c910aa2fd68e3076f0348bd7611b94f91707d6d8b674b9637d4c4f55739712e82cba2aa485a67a602
-  data.tar.gz: c5bbda03afc750f841f22a8eb55a01a4b8a335d8167a81445cadb033e95b40d4409c704c110fefb5a42d752d9abb6d46d5778613b92a9d10a81f25c415b0c569
+  metadata.gz: da91b8a4a865c22dc85853f725eddaacbae069b4550ceebb38cf44cc07ec57c8c29fe0bdabccd0b542a677893af2c6622ac12ae43c8fcb395ae955627729e4f8
+  data.tar.gz: ff3630c3f7f33082ccef8f6b9c30be34e0d0b222c443ad6ff146963b3655d8c4239fa683293954a9fd1f95c8d476a3536b30304289e3c1b476c5c3536ded5297

data/.gitignore

@@ -21,3 +21,4 @@ legion.log
 # SQLite database files
 *.db
 .worktrees
+/docs/

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Legion::Data Changelog
 
+## [1.8.6] - 2026-05-15
+
+### Added
+- Migration 100: creates `apollo_entries` and `apollo_entries_archive` tables on non-Postgres adapters (SQLite etc.), bringing them to parity with the existing Postgres schema.
+- Migration 101: adds `access_scope VARCHAR(20) NOT NULL DEFAULT 'global'`, `identity_principal_id INTEGER`, `identity_id INTEGER`, `identity_canonical_name VARCHAR(255)` columns on both `apollo_entries` and `apollo_entries_archive` across all adapters. Existing rows default to `global` access scope.
+- Migration 102: adds indexes on `apollo_entries` — full index on `access_scope`, partial indexes on `identity_principal_id` and `identity_id` (WHERE NOT NULL) across all adapters.
+
 ## [1.8.5] - 2026-05-09
 
 ### Removed

data/CLAUDE.md

@@ -2,7 +2,7 @@ Always run a full `bundle exec rspec` and `bundle exec rubocop -A` and fix all e
 
 # legion-data
 
-`legion-data` is the persistent storage gem for LegionIO. It owns Sequel database connections, numbered migrations, Sequel models, local SQLite state, extract timing persistence, audit/governance storage, identity/RBAC storage, Apollo storage, and the LLM lifecycle ledger.
+Persistent storage gem for LegionIO. Owns Sequel database connections, numbered migrations, models, local SQLite state, extract timing persistence, audit/governance storage, identity/RBAC storage, Apollo storage, and the LLM lifecycle ledger.
 
 ## Commands
 
@@ -20,7 +20,7 @@ jq '[.examples[] | select(.status != "passed") | {file_path, line_number, full_d
 
 ## Architecture
 
-- `lib/legion/data/connection.rb`: shared Sequel connection setup, diagnostics, fallback handling, query logging.
+- `lib/legion/data/connection.rb`: Sequel connection setup, diagnostics, fallback, query logging.
 - `lib/legion/data/migration.rb`: numbered Sequel migrations.
 - `lib/legion/data/model.rb`: shared model loader.
 - `lib/legion/data/models/`: flat and namespaced Sequel model classes.
@@ -40,12 +40,10 @@ jq '[.examples[] | select(.status != "passed") | {file_path, line_number, full_d
 ## Sequel ORM Rules
 
 Use Sequel associations as the object graph. References:
-
 - https://sequel.jeremyevans.net/rdoc/classes/Sequel/Model/Associations/ClassMethods.html
 - https://github.com/jeremyevans/sequel/blob/master/doc/association_basics.rdoc
 
 Association mapping:
-
 - Foreign key on this model: `many_to_one`.
 - Foreign key on the associated model: `one_to_many` or `one_to_one`.
 - Join table between models: `many_to_many`.
@@ -53,12 +51,43 @@ Association mapping:
 
 When Sequel cannot infer names, set `:class`, `:key`, `:primary_key`, `:join_table`, `:left_key`, and `:right_key` explicitly. Do not create association names that collide with real columns.
 
+## Common Fields Standard
+
+All new tables in legion-data should follow this column convention. Required fields must be present on every table. Optional fields are added when the domain warrants them.
+
+### Required
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `id` | `INTEGER PRIMARY KEY` (auto-increment) | Internal join key — never exposed externally |
+| `identity_principal_id` | `INTEGER` FK → `identity_principals.id` | The principal who caused this row to exist |
+| `identity_id` | `INTEGER` FK → `identities.id` | The specific provider-bound identity credential |
+| `identity_canonical_name` | `VARCHAR(255)` | Denormalized snapshot of the identity's canonical name for fast filtering without joins. This value is a point-in-time copy — it may become stale if the principal is renamed. Use the FK join for authoritative lookups. |
+| `created_at` | `TIMESTAMPTZ` | Row creation time |
+| `updated_at` | `TIMESTAMPTZ` | Last modification time |
+
+### Optional (add when applicable)
+
+| Column | Type | Purpose |
+|--------|------|---------|
+| `expires_at` | `TIMESTAMPTZ` | TTL / archival eligibility |
+| `content_type` | `VARCHAR(...)` | Classifier for the row's payload kind |
+| `conversation_id` | `INTEGER` FK → `llm_conversations.id` | Links to the LLM conversation that produced this row |
+| `contains_phi` | `BOOLEAN` | Row contains Protected Health Information |
+| `contains_pii` | `BOOLEAN` | Row contains Personally Identifiable Information |
+
+### Naming rules
+
+- Identity FKs always use `identity_principal_id` and `identity_id` — never `agent_id`, `principal_id`, `user_id`, or other loose variants for new tables.
+- The denormalized string field is always `identity_canonical_name` — not `canonical_name`, `actor`, `agent_id`, or `identity_name`.
+- Existing columns (`agent_id`, `source_agent`, `submitted_by`, `actor`, etc.) on pre-existing tables are **not renamed or removed** — they are historical record and intentionally left as-is. New identity columns are purely additive.
+
 ## Current Schema Landmarks
 
 - `074`-`076`: Apollo field width, task idempotency, extract step timings.
 - `077`-`090`: LLM lifecycle ledger.
 - `091`-`096`: portable identity companion tables.
-- Namespaced models exist for `Identity::*`, `Apollo::*`, `RBAC::*`, and `LLM::*`.
+- Namespaced models: `Identity::*`, `Apollo::*`, `RBAC::*`, `LLM::*`.
 
 ## Boundaries
 

data/README.md

@@ -403,6 +403,39 @@ Legion::Data.reload_static_cache
 
 ---
 
+## Common Fields Standard
+
+All new tables follow a column convention. Required fields are present on every table. Optional fields are added when the domain warrants them.
+
+### Required
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `id` | `INTEGER PRIMARY KEY` (auto-increment) | Internal join key. Never expose externally — use a `uuid` column for API/log references. |
+| `identity_principal_id` | `INTEGER` FK → `identity_principals.id` | The principal who caused this row to exist. |
+| `identity_id` | `INTEGER` FK → `identities.id` | The specific provider-bound identity credential. |
+| `identity_canonical_name` | `VARCHAR(255)` | Denormalized snapshot of the principal's canonical name. Point-in-time copy — may become stale if the principal is renamed. Use the FK join for authoritative lookups. Exists for fast filtering without joins. |
+| `created_at` | `TIMESTAMPTZ` | Row creation time. |
+| `updated_at` | `TIMESTAMPTZ` | Last modification time. |
+
+### Optional (add when applicable)
+
+| Column | Type | Notes |
+|--------|------|-------|
+| `expires_at` | `TIMESTAMPTZ` | TTL / archival eligibility. |
+| `content_type` | `VARCHAR(...)` | Classifier for the row's payload kind. |
+| `conversation_id` | `INTEGER` FK → `llm_conversations.id` | Links to the LLM conversation that produced this row. |
+| `contains_phi` | `BOOLEAN` | Row contains Protected Health Information. |
+| `contains_pii` | `BOOLEAN` | Row contains Personally Identifiable Information. |
+
+### Naming rules
+
+- Identity FKs are always `identity_principal_id` and `identity_id` — not `principal_id`, `agent_id`, `user_id`, or other loose variants on new tables.
+- The denormalized string column is always `identity_canonical_name` — not `canonical_name`, `actor`, `agent_id`, or `identity_name`.
+- **Existing columns on pre-existing tables are never renamed or removed.** Columns like `agent_id`, `source_agent`, `submitted_by`, and `actor` are historical record. The new identity columns are purely additive.
+
+---
+
 ## Data Models
 
 | Model | Table | Description |
@@ -441,13 +474,13 @@ The `Legion::Data::Model::Identity::*`, `Apollo::*`, and `RBAC::*` namespaces pr
 
 | Model | Table | Description |
 |-------|-------|-------------|
-| `Identity::Provider` | `portable_identity_providers` | Portable provider records with integer primary keys and public UUIDs |
-| `Identity::ProviderCapability` | `portable_identity_provider_capabilities` | Normalized provider capability declarations |
-| `Identity::Principal` | `portable_identity_principals` | Human, service, worker, or system principals |
-| `Identity::Identity` | `portable_identities` | Provider-bound identities for principals |
-| `Identity::Group` | `portable_identity_groups` | Identity groups |
-| `Identity::GroupMembership` | `portable_identity_group_memberships` | Principal and identity group membership rows |
-| `Identity::AuditLog` | `portable_identity_audit_log` | Identity lifecycle and lookup audit events |
+| `Identity::Provider` | `identity_providers` | Provider records with integer primary keys and public UUIDs |
+| `Identity::ProviderCapability` | `identity_provider_capabilities` | Normalized provider capability declarations |
+| `Identity::Principal` | `identity_principals` | Human, service, worker, or system principals |
+| `Identity::Identity` | `identities` | Provider-bound identities for principals |
+| `Identity::Group` | `identity_groups` | Identity groups |
+| `Identity::GroupMembership` | `identity_group_memberships` | Principal and identity group membership rows |
+| `Identity::AuditLog` | `identity_audit_log` | Identity lifecycle and lookup audit events |
 
 ### LLM Lifecycle Models
 

data/lib/legion/data/migrations/100_create_apollo_entries_sqlite.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    next if adapter_scheme == :postgres
+
+    create_table(:apollo_entries) do
+      primary_key :id
+      String :content, text: true, null: false
+      String :content_type, null: false, size: 50
+      Float :confidence, default: 0.5
+      String :source_agent, null: false, size: 255
+      String :source_context, text: true, default: '{}'
+      String :tags, text: true, default: '{}'
+      String :status, null: false, size: 20, default: 'candidate'
+      Integer :access_count, default: 0
+      DateTime :created_at, default: Sequel::CURRENT_TIMESTAMP
+      DateTime :updated_at, default: Sequel::CURRENT_TIMESTAMP
+      DateTime :confirmed_at
+      String :source_provider, size: 255
+      String :source_channel, size: 100
+      String :knowledge_domain, size: 255, default: 'general'
+      String :submitted_by, size: 255
+      String :submitted_from, size: 255
+      String :content_hash, fixed: true, size: 64
+      String :summary_l0, size: 500
+      String :summary_l1, text: true
+      String :knowledge_tier, null: false, size: 4, default: 'L2'
+      String :parent_entry_id, size: 36
+      DateTime :l0_generated_at
+      DateTime :l1_generated_at
+      String :parent_knowledge_id, size: 36
+      TrueClass :is_latest, null: false, default: true
+      String :supersession_type, size: 20
+      DateTime :expires_at
+      String :forget_reason, size: 255
+      TrueClass :is_inference, null: false, default: false
+    end
+
+    create_table(:apollo_entries_archive) do
+      primary_key :id
+      String :content, text: true, null: false
+      String :content_type, null: false, size: 50
+      Float :confidence, default: 0.5
+      String :source_agent, null: false, size: 255
+      String :source_context, text: true, default: '{}'
+      String :tags, text: true, default: '{}'
+      String :status, null: false, size: 20, default: 'candidate'
+      Integer :access_count, default: 0
+      DateTime :created_at, default: Sequel::CURRENT_TIMESTAMP
+      DateTime :updated_at, default: Sequel::CURRENT_TIMESTAMP
+      DateTime :confirmed_at
+      String :source_provider, size: 255
+      String :source_channel, size: 100
+      String :knowledge_domain, size: 255, default: 'general'
+      String :submitted_by, size: 255
+      String :submitted_from, size: 255
+      String :content_hash, fixed: true, size: 64
+      String :summary_l0, size: 500
+      String :summary_l1, text: true
+      String :knowledge_tier, null: false, size: 4, default: 'L2'
+      String :parent_entry_id, size: 36
+      DateTime :l0_generated_at
+      DateTime :l1_generated_at
+      String :parent_knowledge_id, size: 36
+      TrueClass :is_latest, null: false, default: true
+      String :supersession_type, size: 20
+      DateTime :expires_at
+      String :forget_reason, size: 255
+      TrueClass :is_inference, null: false, default: false
+      DateTime :archived_at, default: Sequel::CURRENT_TIMESTAMP
+      String :archive_reason, text: true
+    end
+  end
+
+  down do
+    next if adapter_scheme == :postgres
+
+    drop_table(:apollo_entries_archive) if table_exists?(:apollo_entries_archive)
+    drop_table(:apollo_entries) if table_exists?(:apollo_entries)
+  end
+end

data/lib/legion/data/migrations/101_add_apollo_identity_and_access_scope.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    alter_table(:apollo_entries) do
+      add_column :access_scope,            String, size: 20, null: false, default: 'global'
+      add_column :identity_principal_id,   Integer, null: true
+      add_column :identity_id,             Integer, null: true
+      add_column :identity_canonical_name, String, size: 255, null: true
+    end
+
+    alter_table(:apollo_entries_archive) do
+      add_column :access_scope,            String, size: 20, null: false, default: 'global'
+      add_column :identity_principal_id,   Integer, null: true
+      add_column :identity_id,             Integer, null: true
+      add_column :identity_canonical_name, String, size: 255, null: true
+    end
+  end
+
+  down do
+    alter_table(:apollo_entries) do
+      drop_column :access_scope
+      drop_column :identity_principal_id
+      drop_column :identity_id
+      drop_column :identity_canonical_name
+    end
+
+    alter_table(:apollo_entries_archive) do
+      drop_column :access_scope
+      drop_column :identity_principal_id
+      drop_column :identity_id
+      drop_column :identity_canonical_name
+    end
+  end
+end

data/lib/legion/data/migrations/102_add_apollo_access_scope_and_identity_indexes.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    run 'CREATE INDEX IF NOT EXISTS idx_apollo_access_scope ON apollo_entries (access_scope)'
+    run 'CREATE INDEX IF NOT EXISTS idx_apollo_identity_principal_id ON apollo_entries (identity_principal_id) WHERE identity_principal_id IS NOT NULL'
+    run 'CREATE INDEX IF NOT EXISTS idx_apollo_identity_id ON apollo_entries (identity_id) WHERE identity_id IS NOT NULL'
+  end
+
+  down do
+    run 'DROP INDEX IF EXISTS idx_apollo_access_scope'
+    run 'DROP INDEX IF EXISTS idx_apollo_identity_principal_id'
+    run 'DROP INDEX IF EXISTS idx_apollo_identity_id'
+  end
+end

data/lib/legion/data/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Data
-    VERSION = '1.8.5'
+    VERSION = '1.8.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-data
 version: !ruby/object:Gem::Version
-  version: 1.8.5
+  version: 1.8.6
 platform: ruby
 authors:
 - Esity
@@ -246,6 +246,9 @@ files:
 - lib/legion/data/migrations/097_add_llm_dispatch_fields.rb
 - lib/legion/data/migrations/098_drop_legacy_identity_tables.rb
 - lib/legion/data/migrations/099_rename_portable_identity_tables.rb
+- lib/legion/data/migrations/100_create_apollo_entries_sqlite.rb
+- lib/legion/data/migrations/101_add_apollo_identity_and_access_scope.rb
+- lib/legion/data/migrations/102_add_apollo_access_scope_and_identity_indexes.rb
 - lib/legion/data/model.rb
 - lib/legion/data/models/apollo/access_log.rb
 - lib/legion/data/models/apollo/entries.rb