Skip to content

Latest commit

 

History

History
94 lines (84 loc) · 5.75 KB

knowledge-store.md

File metadata and controls

94 lines (84 loc) · 5.75 KB

Authorized local Create / Update

This K2 write slice builds on the normalized read contract. It adds one backend: SQLite in an existing, explicitly authorized local directory. Create and Update operate only on store-owned candidate bundles. Package and checkout content stay read-only; they are never written, and their IDs cannot be reused in the store. Amending repository-owned content follows the normal scoped PR path.

from pathlib import Path
from inferrsi.knowledge.knowledge_operations import Bundle, KnowledgeReader
from inferrsi.knowledge.knowledge_store import KnowledgeStore

skills = Path("src/inferrsi/knowledge/data/skill_library")
store = KnowledgeStore(Path("/authorized/local/knowledge-workspace"), skill_root=skills)
source = KnowledgeReader(skill_root=skills).read("calibrate-serving-simulation")
draft = Bundle(
    {**source.metadata, "id": "calibrate-serving-simulation-local", "state": "candidate",
     "derived_from": [{"ref": "checkout:calibrate-serving-simulation",
                       "revision": source.revision}]},
    dict(source.content), dict(source.dependencies),
)
revision = store.create(draft)
# Supply a complete amended Bundle, preserving source attribution and resources:
# next_revision = store.update(amended, expected=revision,
#                              reason="Clarify applicability", evidence=[source_pointer])
old = store.read("calibrate-serving-simulation-local", revision=revision)
collected = store.collect(ids=["store:calibrate-serving-simulation-local"],
                          revisions={"store:calibrate-serving-simulation-local": revision},
                          material=True)

skill_root is required: pass the checkout skills root whose IDs must be reserved, or None to declare package-only use. store.reader() / store.collect combine package, checkout and store items with qualified store:<id> refs. An ID owned by the store and a read-only adapter is reported as ambiguous, never shadowed.

Pass a query or relevance to store.collect for local Find discovery. Discovery follows the store's reserved sources. With skill_root=None it searches package Records, projected Skills and store-owned candidates. Store-owned candidates participate using their metadata and entrypoint text. An unpinned query ranks the current revision. A query with a revision pin ranks the retained entrypoint at that revision and returns that same revision if it matches. Use explicit IDs and revisions for exact collection of historical bundles and resource for their contents.

Create and Update

  • Create registers a supplied candidate and rejects duplicate identity. It rejects an ID owned by package or checkout content. An adaptation of existing content uses a distinct ID and records derived_from entries with a qualified ref and the source content revision (or null if unknown).
  • Create does not relabel imported content or generate guidance. Update requires the expected current revision, a reason and an explicit evidence list (empty means none supplied). It publishes a successor without changing the content's state; promotion is not implemented.
  • An Update whose bundle reproduces a retained revision is an explicit conflict. Existing history preserves old metadata, provenance, resources, parent revision, reason and evidence even if a later interpretation changes.
  • If a read-only adapter later gains a store item's ID, reads report ambiguity and further Updates fail with a collision until the owners resolve it.

Writer and publication guarantees

  • Scope: cooperating processes/threads using this API on one local SQLite file; no network-filesystem, distributed-store or hostile filesystem-owner guarantee.
  • The workspace must already exist and lie outside the installed inferrsi package, the checkout containing skill_root and, for a source or editable install, the checkout containing the package (these hold evidence and both matrices). That package checkout is the nearest ancestor holding both pyproject.toml and .git; with skill_root=None it is the only checkout guarded, so a checkout lacking either marker is not protected. The entrypoint of a stored bundle must be UTF-8 text. Workspace and database symlinks are rejected. No destination directory is guessed or automatically created; the caller controls permissions.
  • SQLite BEGIN IMMEDIATE serializes writers before duplicate/stale checks. Resources, revision metadata and the current pointer commit in one transaction. A database error rolls the whole transaction back; partial usable bundles are never published. A five-second lock timeout raises an explicit SQLite error.
  • Content/resource/dependency validation runs before writing. Dependencies are included as bytes and checked against declared digests. Old reads load retained bytes and verify their complete bundle identity; they never fall through to a current checkout. No external mutable dependency lookup occurs during reads.
  • Resource keys cannot be absolute paths or traversal paths; they are database keys, never filesystem write destinations.
  • Runtime operations write only the store database. They do not edit adapter sources, raw evidence or either matrix, and a store candidate is not repository coverage until exported through a reviewed repository change.
  • Normal SQLite local-filesystem transaction guarantees apply. This implementation does not claim tested power-loss durability, malicious tamper resistance or an automatic recovery campaign. Integrity mismatches fail visibly.

Tests use real bundles, SQLite transactions, competing writer connections and a real rejecting database trigger to prove rollback after an insert starts. They do not use hardware, synthetic performance claims or a fake storage implementation.