@askdkc/kiokuko 0.2.7 → 0.2.8

package/docs/execution-ledger.md

@@ -0,0 +1,89 @@
+# Execution ledger
+
+The execution ledger is an append-oriented audit of agent runs. It is separate from curated memory (`entries`, `entry_revisions`, `entry_revision_tags`, `entry_links`) and from memory mutation audit (`audit_events`). A ledger event never becomes verified memory automatically.
+
+## Storage model
+
+Migration `004_agent_gateway.sql` adds:
+
+- `ledger_runs`: immutable workspace/client/protocol/capture/coverage identity and mutable lifecycle cursor/status.
+- `run_intakes`: one-to-one link from a run to an existing Akinator session, including policy/schema versions, field sources, initial profile hash, and recommended tags.
+- `intake_feedback`: question/profile feedback with XOR target and actor/idempotency uniqueness.
+- `ledger_events`: contiguous local sequence, source identity, canonical/source types, bounded sanitized payload, redaction metadata, and hash-chain fields.
+- `ledger_evidence`: bounded command/test/file/diff/URL/artifact locators and digests; never binary or unlimited output.
+- `context_deliveries` and `context_delivery_entries`: exact cursor/profile/query/policy/budget and selected immutable entry revision/rank/score/reason. The child row has a composite foreign key to `entry_revisions`, so a delivery cannot reference a missing or silently substituted revision.
+- `context_feedback` and `run_feedback`: explicit weak ranking signals and outcome/recommendation feedback.
+- `ledger_memory_links`: provenance from run/event/delivery to promoted candidate memory.
+- `ledger_purge_audit`: content-free tombstones after privacy purge.
+
+Migration `010_nudge_deliveries.sql` adds:
+
+- `nudge_deliveries`: presentation history for selected advisory nudges. It stores the run, policy version, checkpoint identity, logical occurrence, code, sequence, priority, and bounded evidence/reference ID snapshots, but not rendered message text.
+
+Migration `011_nudge_integrity.sql` adds database guards for the supported nudge policy, code/priority pairs, and bounded JSON snapshots.
+
+Enno client routing writes `enno.client_bound` for the first session route and
+`enno.client_rebound` for later route changes. The payload records the previous
+and current client kind, session ID, and version projection; a rebound clears
+the old version. These events audit routing changes and do not confer ownership
+or advance the Enno contract state.
+
+The Enno execution ledger also uses database-backed ownership rows rather than
+process memory. Resume tokens are stored only as hashes and bind a route epoch;
+rerouting invalidates old epochs. A WorkUnit execution lease prevents two local
+clients from reporting the same unit and blocks rerouting while current.
+Operation receipts and verifier runs have `started`, `completed`, `failed`, and
+`abandoned` states with bounded leases and owner nonces. Recovery atomically
+abandons an expired owner before one new owner claims the exact operation; a
+losing or stale nonce cannot complete it.
+
+Final evidence binds contract revision, mutation revision, verifier
+specification digest, and complete repository-state digests captured before and
+after verifier execution. A verifier-caused repository mutation marks the run
+unacceptable, and any later HEAD/index/worktree/untracked/symlink change makes
+the evidence stale before `enno_finish` can commit.
+
+## Invariants
+
+1. A run belongs to one workspace for its lifetime.
+2. One run links to one intake session, and one intake session links to one run; their workspaces must match.
+3. `intake → active` is valid only after the linked session is `ready` or `exhausted`.
+4. A run's coverage declaration is preserved rather than inferred upward.
+5. `event_id` is globally unique; events also have unique `(run_id, sequence)` and unique `(run_id, source_event_id)` when present. Exact replay may identify an event by its explicit `eventId` or its run-scoped source identity; a different sanitized body conflicts.
+6. A batch receives contiguous local sequence numbers in one `BEGIN IMMEDIATE` transaction or writes nothing.
+7. Corrections and task-profile revisions are new events; prior event rows and finalized intake profiles are not rewritten.
+8. Terminal runs reject new events except exact replay of an acknowledged idempotency/source identity.
+9. Delivery rows reference entry revisions instead of copying memory bodies.
+10. Feedback cannot mutate entry status/trust or an existing policy/session/profile.
+11. Promotion is explicit, creates `candidate` memory only, and records provenance.
+
+## Canonical event types
+
+V1 recognizes intake/run/request/constraint/decision/step/approval/tool/command/file/test/verification/error/retry/cancellation/context/memory/task-profile/correction/source event families. Unknown client event names are retained only as `sourceType` behind the canonical `source.event` type; they are not invented or silently mapped.
+
+## Integrity chain
+
+Before storage, Kiokuko performs strict validation, creates an owned JSON snapshot, recursively sanitizes keys/values/URLs/paths/environment data, enforces byte limits, and canonicalizes JSON. Optional hash fields are represented explicitly as `null`, so the write-time preimage is identical after a SQLite round trip. The event hash commits to run ID, local sequence, canonical event data, sanitized payload, and previous hash. The first event uses the deterministic genesis hash. `doctor` checks contiguous sequence, run cursor, hash links, and orphans.
+
+One sanitized event payload, task snapshot, profile-hints snapshot, intake-answer snapshot, or run-metadata snapshot is limited to 64 KiB. The limit is applied after sanitization and before hashing or opening a write transaction.
+
+The chain is tamper-evident, not a signature or remote attestation. SQLite and same-user host security still define the local trust boundary.
+
+## Projection and evidence freshness
+
+Projection is deterministic through a committed local sequence. It derives current task profile from the immutable intake profile plus ordered `task_profile.revised` events, unresolved failures, unknown side effects, latest mutation, and latest passing verification. Evidence state is:
+
+- `none`: no verification evidence;
+- `failed`: latest relevant verification failed;
+- `fresh`: passing verification is at or after the latest mutation;
+- `stale`: a later mutation exists.
+
+Minimum recommendation codes are `INTAKE_INCOMPLETE`, `VERIFY_AFTER_MUTATION`, `SIDE_EFFECT_OUTCOME_UNKNOWN`, `UNRESOLVED_FAILURE`, `CONTEXT_STALE`, `CONTRADICTORY_MEMORY`, `COVERAGE_INCOMPLETE`, and `PROMOTION_CANDIDATE`. Recommendations are stored data with evidence IDs, not commands.
+
+Recommendations describe every currently applicable deterministic condition. A nudge is a separate presentation decision: at most one eligible advisory item selected from the v1 nudge subset (`SIDE_EFFECT_OUTCOME_UNKNOWN`, `UNRESOLVED_FAILURE`, and `VERIFY_AFTER_MUTATION`). `CONTRADICTORY_MEMORY` remains a recommendation but is not a nudge because the HTTP checkpoint broker does not currently expose its complete contradiction-pair state. Nudge candidates are derived from the committed projection and final capability-gated recommendations only; fixed messages and bounded evidence/reference IDs are returned, and rate limiting never removes the corresponding recommendation.
+
+Nudge policy version `nudges.v1` shows one logical occurrence at most once per run, permits at most three deliveries per run, and requires at least three committed ledger sequence positions between deliveries of the same code. Eligibility uses occurrence identity and ledger sequence, not wall-clock time. `nudge_deliveries` is presentation history outside `ledger_events`, so delivering a nudge cannot change the execution projection.
+
+## Archive, backup, purge
+
+Existing memory export remains memory-only. Ledger export/import uses a separate deterministic manifest/checksum and includes nudge delivery history. Full SQLite backup contains memory, ledger, nudge deliveries, and feedback. Purge removes bounded content under explicit confirmation while preserving only a content-free tombstone and any promoted memory that has its own lifecycle.

package/docs/release-notes-0.1.18.md

@@ -0,0 +1,103 @@
+# Kiokuko 0.1.18
+
+## External Skills
+
+- Added bounded provider search, commit-pinned source validation, chunk limits, snapshot idempotency, and shared discovery single-flight.
+- Added `kiokuko skills find|import|list|show|refresh|disable|enable|prune-cache`.
+- Manual Skill import is now create-only and accepts only an exact locally
+  reviewed catalog identity. Re-importing an existing identity is a conflict;
+  use `skills refresh` for an existing managed Skill.
+- Akinator discovery and `kiokuko skills find` now use one shared provider-backed search operation; the temporary capability-fallback response was removed.
+- Akinator task preparation now defaults to reference-only `official` discovery; `off` remains available and `community` remains explicit opt-in.
+- Interactive setup now asks before enabling audited community discovery and persists the selected mode in each managed MCP client configuration; batch setup uses `--skill-discovery`.
+- Added authenticated local Web UI/API visibility for imported external skills.
+- Disabled, stale, blocked, and unmanaged external references are excluded from retrieval and Curator globalization.
+- Community-mode candidates fail closed without a successful provider audit.
+- Unknown capability catalogs now force official-only discovery; imported Skill
+  reuse requires explicit applicability and mode-compatible provenance.
+- Multiple relevant Skills can be imported from one repository, and lifecycle
+  CLI commands resolve both internal IDs and `owner/repository/skill` paths.
+- Task preparation replay identity now includes the effective discovery mode
+  and a bounded normalized capability-catalog hash, so changed discovery input
+  cannot reuse an older context delivery.
+- `task_prepare` now requires a bounded client-generated `requestId`. The same
+  ID and bound input replay one run; a changed bound request under that ID
+  conflicts, while a new ID opens a distinct run even for identical task text.
+  The raw ID is not stored and `client.sessionId` is not used as a turn ID. The
+  normalized context budget is bound and must match on `task_answer`.
+- Generated agent/setup/MCP contracts now require an available local
+  `memory-reasoning` Skill to be read before code modification and recalled
+  claims to be converted into verified premises, invariants, counterexamples,
+  and regression tests; availability alone is not compliance.
+- A v1 provider response with exact HTTP 401 authentication failure falls back
+  once per query to the Compatibility Provider, with provider-separated
+  negative and result caches. Other authentication and protocol failures stop.
+- Removed legacy fixed-source sync and guessed-source fallback. Bounded exact
+  verification of reviewed catalog-pinned sources remains. The ungated
+  `guide context` compatibility command was removed; task-aware ContextBroker
+  output is capability-gated.
+
+External skills remain untrusted candidate references. Kiokuko does not install,
+execute, verify, globalize, or register fetched skill content automatically.
+
+## Fail-closed storage and setup
+
+- Fixed Windows OpenCode setup writing MCP configuration, global instructions,
+  and bundled skills under `%APPDATA%\opencode`; setup now follows OpenCode's
+  XDG global directory resolution.
+- Setup now rejects duplicate or semantically colliding JSON/TOML configuration,
+  malformed UTF-8, symlink escapes, and concurrent target changes before it can
+  silently merge or overwrite them. Exact concurrent `use` results converge once;
+  incompatible state remains an explicit conflict.
+- Migration and repository transactions now surface rollback failures, and
+  verified pre-migration backups complete before any schema mutation.
+- Node.js 24.16 is now the minimum runtime. Manual and pre-migration SQLite
+  backups serialize the exact already-open connection and install a verified,
+  create-only artifact; the retired pathname-reopening backup subprocess and
+  overwrite behavior were removed. `kiokuko backup` no longer initializes or
+  migrates its source.
+- Project binding rejects the reserved global identity. Forced rebinding now
+  requires a distinct repository/workspace pair and performs an exact database
+  location compare-and-swap or fails; it never mutates a repository workspace
+  in place or silently retains the old identity. Moving `agentFile` removes
+  only the old marked block, preserves human bytes and mode, and conditionally
+  restores all owned file mutations if a later step fails. Skipping an agent
+  write rejects any stale managed block at the prospective target.
+- Repository binding/template versions are downgrade-protected across files and
+  SQLite metadata. Missing, malformed, corrupt, or future version metadata fails
+  explicitly. An indeterminate SQLite commit is surfaced as such and retains
+  the matching installed files instead of risking split-brain compensation.
+- Stored revision chains, hashes, structured scope, projections, and context
+  replay state are validated from their exact persisted identities. Corruption
+  fails explicitly instead of being skipped or normalized into a new identity.
+- Migration 012 validates the persisted structural identity of released
+  `context-ranking-v2` and `context-ranking-v3` scoped deliveries during setup.
+  Original delivery IDs, policy versions, character metadata, delivery items,
+  and all historical references are preserved. Legacy preview text was not
+  persisted and is not reconstructed during upgrade. Legacy deliveries remain
+  available for audit and feedback references but are never replayed as current
+  `context-ranking-v4` context; invalid persisted legacy structure aborts the
+  migration transaction. New scoped deliveries continue to use
+  `context-ranking-v4`.
+- Migration 009 transactionally rewrites the one exact released locale-ordered
+  revision preimage to the canonical hash and scope. Forged preimages and
+  canonical collisions abort the upgrade; runtime compatibility hashing was
+  removed completely.
+- Workspace archive v2 is intentionally limited to revision-1 current state.
+  Import/export use one strict canonical format, bounded input, complete secret
+  scanning, snapshot-consistent reads, and create-only output. Use a full SQLite
+  backup when immutable revision history must be preserved.
+
+## Model task boundary
+
+- Removed the direct model-facing `memory_recall` and
+  `claude_prompt_context` MCP tools. Task memory now enters through
+  `task_prepare` / `task_answer`; checkpoint and Curator tools remain lifecycle
+  operations.
+- Removed generic JSON `call` operations that returned memory through `read`,
+  `search`, or scoped/unscoped `recall`. Direct CLI/Web inspection remains a
+  human/operator management surface.
+- Setup no longer installs Claude prompt hooks or the OpenCode loop guard and
+  no longer accepts their CLI options. During upgrade it removes only the exact
+  retired managed hook/guard; modified or ambiguous legacy identities fail
+  explicitly and unrelated settings are preserved.

package/docs/retrieval-evaluation.md

@@ -0,0 +1,10 @@
+# Retrieval evaluation
+
+The existing evaluation keeps lexical and exact-signal lanes as baselines and
+preserves weighted reciprocal-rank fusion. Local semantic evaluation covers
+Japanese, English, Simplified Chinese, Korean, technical identifiers, stale
+vectors, scope boundaries, and query-cache privacy.
+
+Run the deterministic suite with `npm run test:evaluation`. Run the installed
+model probe with `node scripts/run-local-embedding-smoke.mjs --offline` when a
+verified local model directory is available.

package/docs/security.md

@@ -0,0 +1,11 @@
+# Embedding security
+
+The local-small preset fixes the repository, full revision, required files,
+sizes, and SHA-256 values. Arbitrary repositories, URLs, paths, extensions,
+and remote code are not accepted. Files are verified before model loading;
+staging is private and final installation is atomic.
+
+Status, doctor, progress, and errors do not include memory text, query text,
+credentials, redirect URLs, or absolute model paths. Legacy embedding
+environment variables are detected by name only and are not used as runtime
+configuration.

package/docs/sqlite-driver-adr.md

@@ -0,0 +1,8 @@
+# SQLite driver ADR
+
+Kiokuko keeps JavaScript exact-cosine search as the portable fallback and uses
+the package-owned sqlite-vec extension only when the configured backend is
+`auto` or `sqlite-vec` and the extension loads successfully. The setup model
+and embedding profile are independent of that backend choice. Extension
+loading is disabled immediately after a successful load, and user-provided
+native extension paths are not accepted.

package/migrations/022_embedding_setup_v2.sql

@@ -0,0 +1,236 @@
+-- Persist local embedding setup state while retaining the immutable v1
+-- semantic projections. This migration performs no model or network I/O.
+
+CREATE TABLE embedding_profiles_v2 (
+    profile_id TEXT PRIMARY KEY
+        CHECK (length(profile_id) = 64 AND profile_id NOT GLOB '*[^0-9a-f]*'),
+    schema_version INTEGER NOT NULL DEFAULT 1 CHECK (schema_version IN (1, 2)),
+    provider_kind TEXT NOT NULL
+        CHECK (provider_kind IN ('openai-compatible', 'local-transformers')),
+    endpoint_fingerprint TEXT
+        CHECK (endpoint_fingerprint IS NULL OR (length(endpoint_fingerprint) = 64 AND endpoint_fingerprint NOT GLOB '*[^0-9a-f]*')),
+    model TEXT NOT NULL,
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    distance_metric TEXT NOT NULL CHECK (distance_metric = 'cosine'),
+    distance_ceiling REAL NOT NULL CHECK (distance_ceiling > 0.0 AND distance_ceiling < 2.0),
+    document_template_version INTEGER NOT NULL CHECK (document_template_version > 0),
+    query_template_version INTEGER NOT NULL CHECK (query_template_version > 0),
+    preset_id TEXT,
+    source_model TEXT,
+    artifact_repository TEXT,
+    model_revision TEXT,
+    artifact_manifest_hash TEXT
+        CHECK (artifact_manifest_hash IS NULL OR (length(artifact_manifest_hash) = 64 AND artifact_manifest_hash NOT GLOB '*[^0-9a-f]*')),
+    inference_engine TEXT,
+    inference_engine_version TEXT,
+    dtype TEXT,
+    pooling TEXT,
+    normalize INTEGER CHECK (normalize IS NULL OR normalize IN (0, 1)),
+    maximum_tokens INTEGER CHECK (maximum_tokens IS NULL OR maximum_tokens > 0),
+    input_contract TEXT,
+    query_prefix TEXT,
+    document_prefix TEXT,
+    created_at TEXT NOT NULL,
+    CHECK (
+        (schema_version = 1 AND provider_kind = 'openai-compatible'
+            AND endpoint_fingerprint IS NOT NULL
+            AND preset_id IS NULL AND source_model IS NULL AND artifact_repository IS NULL
+            AND model_revision IS NULL AND artifact_manifest_hash IS NULL
+            AND inference_engine IS NULL AND inference_engine_version IS NULL
+            AND dtype IS NULL AND pooling IS NULL AND normalize IS NULL
+            AND maximum_tokens IS NULL AND input_contract IS NULL
+            AND query_prefix IS NULL AND document_prefix IS NULL)
+        OR
+        (schema_version = 2 AND provider_kind = 'local-transformers'
+            AND endpoint_fingerprint IS NULL
+            AND preset_id IS NOT NULL AND source_model IS NOT NULL
+            AND artifact_repository IS NOT NULL AND model_revision IS NOT NULL
+            AND artifact_manifest_hash IS NOT NULL AND inference_engine IS NOT NULL
+            AND inference_engine_version IS NOT NULL AND dtype IS NOT NULL
+            AND pooling IS NOT NULL AND normalize IS NOT NULL
+            AND maximum_tokens IS NOT NULL AND input_contract IS NOT NULL
+            AND query_prefix IS NOT NULL AND document_prefix IS NOT NULL)
+    )
+);
+
+INSERT INTO embedding_profiles_v2 (
+    profile_id, schema_version, provider_kind, endpoint_fingerprint, model,
+    dimensions, distance_metric, distance_ceiling, document_template_version,
+    query_template_version, created_at
+)
+SELECT profile_id, 1, provider_kind, endpoint_fingerprint, model,
+       dimensions, distance_metric, distance_ceiling, document_template_version,
+       query_template_version, created_at
+  FROM embedding_profiles;
+
+CREATE TABLE embedding_runtime_v2 (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    active_profile_id TEXT REFERENCES embedding_profiles_v2(profile_id),
+    generation INTEGER NOT NULL CHECK (generation > 0),
+    activated_at TEXT
+);
+
+INSERT INTO embedding_runtime_v2 (singleton, active_profile_id, generation, activated_at)
+SELECT singleton, active_profile_id, generation, activated_at
+  FROM embedding_runtime;
+
+CREATE TABLE entry_embeddings_v2 (
+    entry_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v2(profile_id) ON DELETE CASCADE,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    content_hash TEXT NOT NULL,
+    document_hash TEXT NOT NULL CHECK (length(document_hash) = 64 AND document_hash NOT GLOB '*[^0-9a-f]*'),
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    embedding BLOB NOT NULL,
+    vector_hash TEXT NOT NULL CHECK (length(vector_hash) = 64 AND vector_hash NOT GLOB '*[^0-9a-f]*'),
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (entry_id, profile_id),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE,
+    CHECK (length(embedding) = dimensions * 4)
+);
+
+INSERT INTO entry_embeddings_v2 (
+    entry_id, profile_id, revision, content_hash, document_hash, dimensions,
+    embedding, vector_hash, created_at
+)
+SELECT entry_id, profile_id, revision, content_hash, document_hash, dimensions,
+       embedding, vector_hash, created_at
+  FROM entry_embeddings;
+
+CREATE TABLE embedding_jobs_v2 (
+    entry_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v2(profile_id) ON DELETE CASCADE,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    content_hash TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('pending', 'leased', 'failed', 'blocked')),
+    attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+    available_at TEXT NOT NULL,
+    lease_id TEXT,
+    lease_expires_at TEXT,
+    error_code TEXT CHECK (error_code IS NULL OR error_code IN (
+        'timeout', 'rate_limited', 'provider_unavailable', 'invalid_response',
+        'dimension_mismatch', 'secret_blocked', 'profile_changed', 'entry_changed'
+    )),
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (entry_id, profile_id),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE,
+    CHECK (
+        (state = 'leased' AND lease_id IS NOT NULL AND lease_expires_at IS NOT NULL)
+        OR (state <> 'leased' AND lease_id IS NULL AND lease_expires_at IS NULL)
+    )
+);
+
+INSERT INTO embedding_jobs_v2 (
+    entry_id, profile_id, revision, content_hash, state, attempts,
+    available_at, lease_id, lease_expires_at, error_code, created_at, updated_at
+)
+SELECT entry_id, profile_id, revision, content_hash, state, attempts,
+       available_at, lease_id, lease_expires_at, error_code, created_at, updated_at
+  FROM embedding_jobs;
+
+CREATE TABLE query_embeddings_v2 (
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v2(profile_id) ON DELETE CASCADE,
+    query_hash TEXT NOT NULL CHECK (length(query_hash) = 64 AND query_hash NOT GLOB '*[^0-9a-f]*'),
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    embedding BLOB NOT NULL,
+    vector_hash TEXT NOT NULL CHECK (length(vector_hash) = 64 AND vector_hash NOT GLOB '*[^0-9a-f]*'),
+    created_at TEXT NOT NULL,
+    last_used_at TEXT NOT NULL,
+    PRIMARY KEY (profile_id, query_hash),
+    CHECK (length(embedding) = dimensions * 4)
+);
+
+INSERT INTO query_embeddings_v2 (
+    profile_id, query_hash, dimensions, embedding, vector_hash, created_at, last_used_at
+)
+SELECT profile_id, query_hash, dimensions, embedding, vector_hash, created_at, last_used_at
+  FROM query_embeddings;
+
+DROP INDEX idx_query_embeddings_lru;
+DROP TABLE query_embeddings;
+DROP INDEX idx_embedding_jobs_claim;
+DROP TABLE embedding_jobs;
+DROP INDEX idx_entry_embeddings_profile_revision;
+DROP TABLE entry_embeddings;
+DROP TABLE embedding_runtime;
+DROP TRIGGER embedding_profiles_immutable_update;
+DROP TABLE embedding_profiles;
+
+ALTER TABLE embedding_profiles_v2 RENAME TO embedding_profiles;
+ALTER TABLE embedding_runtime_v2 RENAME TO embedding_runtime;
+ALTER TABLE entry_embeddings_v2 RENAME TO entry_embeddings;
+ALTER TABLE embedding_jobs_v2 RENAME TO embedding_jobs;
+ALTER TABLE query_embeddings_v2 RENAME TO query_embeddings;
+
+CREATE TRIGGER embedding_profiles_immutable_update
+BEFORE UPDATE ON embedding_profiles
+BEGIN
+    SELECT RAISE(ABORT, 'embedding_profiles are immutable');
+END;
+
+CREATE INDEX idx_entry_embeddings_profile_revision
+    ON entry_embeddings(profile_id, entry_id, revision);
+CREATE INDEX idx_embedding_jobs_claim
+    ON embedding_jobs(profile_id, state, available_at, entry_id);
+CREATE INDEX idx_query_embeddings_lru
+    ON query_embeddings(profile_id, last_used_at, query_hash);
+
+CREATE TABLE embedding_model_installations (
+    installation_id TEXT PRIMARY KEY,
+    preset_id TEXT NOT NULL,
+    repository_id TEXT NOT NULL,
+    revision TEXT NOT NULL,
+    artifact_manifest_hash TEXT NOT NULL CHECK (length(artifact_manifest_hash) = 64 AND artifact_manifest_hash NOT GLOB '*[^0-9a-f]*'),
+    relative_path TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('staging', 'verified', 'corrupt', 'missing')),
+    total_bytes INTEGER NOT NULL CHECK (total_bytes >= 0),
+    installed_at TEXT NOT NULL,
+    verified_at TEXT,
+    last_checked_at TEXT NOT NULL
+);
+
+CREATE TABLE embedding_settings (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    mode TEXT NOT NULL CHECK (mode IN ('off', 'optional', 'required')),
+    provider_kind TEXT CHECK (provider_kind IS NULL OR provider_kind IN ('local-transformers', 'openai-compatible', 'legacy-environment')),
+    preset_id TEXT,
+    model_installation_id TEXT REFERENCES embedding_model_installations(installation_id),
+    vector_backend TEXT NOT NULL CHECK (vector_backend IN ('auto', 'javascript', 'sqlite-vec')),
+    batch_size INTEGER NOT NULL CHECK (batch_size BETWEEN 1 AND 64),
+    timeout_ms INTEGER NOT NULL CHECK (timeout_ms BETWEEN 100 AND 120000),
+    legacy_profile_id TEXT REFERENCES embedding_profiles(profile_id),
+    setup_state TEXT NOT NULL CHECK (setup_state IN ('disabled', 'requires_setup', 'installing', 'ready', 'degraded')),
+    updated_at TEXT NOT NULL
+);
+
+INSERT INTO embedding_settings (
+    singleton, mode, provider_kind, preset_id, model_installation_id,
+    vector_backend, batch_size, timeout_ms, legacy_profile_id, setup_state, updated_at
+)
+SELECT 1,
+       'off',
+       CASE WHEN r.active_profile_id IS NULL THEN NULL ELSE 'legacy-environment' END,
+       NULL,
+       NULL,
+       'auto',
+       16,
+       30000,
+       r.active_profile_id,
+       CASE WHEN r.active_profile_id IS NULL THEN 'disabled' ELSE 'requires_setup' END,
+       COALESCE(r.activated_at, '1970-01-01T00:00:00.000Z')
+  FROM embedding_runtime AS r;
+
+CREATE TABLE embedding_setup_runs (
+    setup_id TEXT PRIMARY KEY,
+    preset_id TEXT NOT NULL,
+    phase TEXT NOT NULL CHECK (phase IN ('planned', 'downloading', 'verifying', 'probing', 'activating', 'embedding', 'completed', 'failed')),
+    model_installation_id TEXT REFERENCES embedding_model_installations(installation_id),
+    active_profile_id TEXT REFERENCES embedding_profiles(profile_id),
+    initial_entry_count INTEGER NOT NULL CHECK (initial_entry_count >= 0),
+    processed_entry_count INTEGER NOT NULL CHECK (processed_entry_count >= 0),
+    failure_code TEXT,
+    started_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    completed_at TEXT
+);

package/migrations/down/022_embedding_setup_v2.sql

@@ -0,0 +1,133 @@
+-- Manual rollback for migration 022. Stop every Kiokuko process and make a
+-- full SQLite backup before running this script. Local v2 profiles are not
+-- silently converted to the v1 representation.
+
+BEGIN IMMEDIATE;
+
+CREATE TEMP TRIGGER embedding_setup_v2_rollback_guard
+BEFORE DELETE ON schema_migrations
+WHEN EXISTS (SELECT 1 FROM embedding_profiles WHERE schema_version = 2)
+BEGIN
+    SELECT RAISE(ABORT, 'migration 022 rollback requires removing local v2 profiles explicitly');
+END;
+
+CREATE TABLE embedding_profiles_v1 (
+    profile_id TEXT PRIMARY KEY CHECK (length(profile_id) = 64 AND profile_id NOT GLOB '*[^0-9a-f]*'),
+    provider_kind TEXT NOT NULL CHECK (provider_kind IN ('openai-compatible')),
+    endpoint_fingerprint TEXT NOT NULL CHECK (length(endpoint_fingerprint) = 64 AND endpoint_fingerprint NOT GLOB '*[^0-9a-f]*'),
+    model TEXT NOT NULL,
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    distance_metric TEXT NOT NULL CHECK (distance_metric = 'cosine'),
+    distance_ceiling REAL NOT NULL CHECK (distance_ceiling > 0.0 AND distance_ceiling < 2.0),
+    document_template_version INTEGER NOT NULL CHECK (document_template_version > 0),
+    query_template_version INTEGER NOT NULL CHECK (query_template_version > 0),
+    created_at TEXT NOT NULL
+);
+INSERT INTO embedding_profiles_v1 (
+    profile_id, provider_kind, endpoint_fingerprint, model, dimensions,
+    distance_metric, distance_ceiling, document_template_version,
+    query_template_version, created_at
+)
+SELECT profile_id, provider_kind, endpoint_fingerprint, model, dimensions,
+       distance_metric, distance_ceiling, document_template_version,
+       query_template_version, created_at
+  FROM embedding_profiles;
+
+CREATE TABLE embedding_runtime_v1 (
+    singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+    active_profile_id TEXT REFERENCES embedding_profiles_v1(profile_id),
+    generation INTEGER NOT NULL CHECK (generation > 0),
+    activated_at TEXT
+);
+INSERT INTO embedding_runtime_v1 (singleton, active_profile_id, generation, activated_at)
+SELECT singleton, active_profile_id, generation, activated_at FROM embedding_runtime;
+
+CREATE TABLE entry_embeddings_v1 (
+    entry_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v1(profile_id) ON DELETE CASCADE,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    content_hash TEXT NOT NULL,
+    document_hash TEXT NOT NULL CHECK (length(document_hash) = 64 AND document_hash NOT GLOB '*[^0-9a-f]*'),
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    embedding BLOB NOT NULL,
+    vector_hash TEXT NOT NULL CHECK (length(vector_hash) = 64 AND vector_hash NOT GLOB '*[^0-9a-f]*'),
+    created_at TEXT NOT NULL,
+    PRIMARY KEY (entry_id, profile_id),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE,
+    CHECK (length(embedding) = dimensions * 4)
+);
+INSERT INTO entry_embeddings_v1 SELECT * FROM entry_embeddings;
+
+CREATE TABLE embedding_jobs_v1 (
+    entry_id TEXT NOT NULL,
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v1(profile_id) ON DELETE CASCADE,
+    revision INTEGER NOT NULL CHECK (revision > 0),
+    content_hash TEXT NOT NULL,
+    state TEXT NOT NULL CHECK (state IN ('pending', 'leased', 'failed', 'blocked')),
+    attempts INTEGER NOT NULL DEFAULT 0 CHECK (attempts >= 0),
+    available_at TEXT NOT NULL,
+    lease_id TEXT,
+    lease_expires_at TEXT,
+    error_code TEXT CHECK (error_code IS NULL OR error_code IN (
+        'timeout', 'rate_limited', 'provider_unavailable', 'invalid_response',
+        'dimension_mismatch', 'secret_blocked', 'profile_changed', 'entry_changed'
+    )),
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    PRIMARY KEY (entry_id, profile_id),
+    FOREIGN KEY (entry_id, revision) REFERENCES entry_revisions(entry_id, revision) ON DELETE CASCADE,
+    CHECK (
+        (state = 'leased' AND lease_id IS NOT NULL AND lease_expires_at IS NOT NULL)
+        OR (state <> 'leased' AND lease_id IS NULL AND lease_expires_at IS NULL)
+    )
+);
+INSERT INTO embedding_jobs_v1 SELECT * FROM embedding_jobs;
+
+CREATE TABLE query_embeddings_v1 (
+    profile_id TEXT NOT NULL REFERENCES embedding_profiles_v1(profile_id) ON DELETE CASCADE,
+    query_hash TEXT NOT NULL CHECK (length(query_hash) = 64 AND query_hash NOT GLOB '*[^0-9a-f]*'),
+    dimensions INTEGER NOT NULL CHECK (dimensions BETWEEN 2 AND 8192),
+    embedding BLOB NOT NULL,
+    vector_hash TEXT NOT NULL CHECK (length(vector_hash) = 64 AND vector_hash NOT GLOB '*[^0-9a-f]*'),
+    created_at TEXT NOT NULL,
+    last_used_at TEXT NOT NULL,
+    PRIMARY KEY (profile_id, query_hash),
+    CHECK (length(embedding) = dimensions * 4)
+);
+INSERT INTO query_embeddings_v1 SELECT * FROM query_embeddings;
+
+DELETE FROM schema_migrations WHERE version = 22 AND name = '022_embedding_setup_v2.sql';
+DROP TRIGGER embedding_setup_v2_rollback_guard;
+
+DROP TABLE embedding_setup_runs;
+DROP TABLE embedding_settings;
+DROP TABLE embedding_model_installations;
+DROP INDEX idx_query_embeddings_lru;
+DROP TABLE query_embeddings;
+DROP INDEX idx_embedding_jobs_claim;
+DROP TABLE embedding_jobs;
+DROP INDEX idx_entry_embeddings_profile_revision;
+DROP TABLE entry_embeddings;
+DROP TABLE embedding_runtime;
+DROP TRIGGER embedding_profiles_immutable_update;
+DROP TABLE embedding_profiles;
+
+ALTER TABLE embedding_profiles_v1 RENAME TO embedding_profiles;
+ALTER TABLE embedding_runtime_v1 RENAME TO embedding_runtime;
+ALTER TABLE entry_embeddings_v1 RENAME TO entry_embeddings;
+ALTER TABLE embedding_jobs_v1 RENAME TO embedding_jobs;
+ALTER TABLE query_embeddings_v1 RENAME TO query_embeddings;
+
+CREATE TRIGGER embedding_profiles_immutable_update
+BEFORE UPDATE ON embedding_profiles
+BEGIN
+    SELECT RAISE(ABORT, 'embedding_profiles are immutable');
+END;
+CREATE INDEX idx_entry_embeddings_profile_revision
+    ON entry_embeddings(profile_id, entry_id, revision);
+CREATE INDEX idx_embedding_jobs_claim
+    ON embedding_jobs(profile_id, state, available_at, entry_id);
+CREATE INDEX idx_query_embeddings_lru
+    ON query_embeddings(profile_id, last_used_at, query_hash);
+
+COMMIT;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@askdkc/kiokuko",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "description": "Model-agnostic external memory for AI coding agents",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "dist/",
     "migrations/",
     "skills/",
+    "docs/",
     "templates/",
     "README.md",
     "README.ja.md",
@@ -53,6 +54,8 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
+    "@huggingface/hub": "2.16.1",
+    "@huggingface/transformers": "4.2.0",
     "sqlite-vec": "0.1.9"
   },
   "devDependencies": {