Governance
Governed Company Brain
Query the factory's governed portfolio with citations, grants and append-only history.
An exact projection of the portfolio
The Company Brain is the exact, governed projection of what a software factory knows about its own portfolio: products (prod), projects (proj) and initiatives (init). It is not OrkMind's semantic memory of collections, tags and search: it lives in its own PostgreSQL tables and only answers what an authorized producer recorded, citing where each item came from.
The context mode, the history operation and this documentation are on the repository's main branch, in the Unreleased section of the CHANGELOG. They are not yet part of a version published on PyPI.
Separate contract and API
The orkmind. contract is the same file in OrkMind and Orkastery, byte for byte. Its sha256 is reported by capabilities as contract_hash, and Orkastery refuses a Brain with a different hash. Calls use the orkmind. envelope: new operations are added to it without changing contract_hash. The context package and history belong to this API.
Validation is strict: unknown fields are rejected, the id starts with the kind, proj only has a prod parent and init only has a proj parent. Failures come out as a brain.* code, without echoing the content.
Identity from the login, explicit grants
Identity comes only from the authenticated PostgreSQL login, which the database administrator maps to a human or service principal. No request field, environment variable or tool argument names a principal. Grants apply per tenant, principal and ACL, with actions, resources, source instances, visible fields and validity; revocation takes effect on the next call.
get,queryandhistoryare for human principals only.ingest,migrateandrollbackare for service principals only.- Without a grant for the action, a read answers as if the entity did not exist.
Operations from the CLI and MCP
orkmind brain request reads a JSON envelope on stdin and writes the response to stdout; the orkmind_brain MCP tool takes the same envelope. The DSN comes from ORKMIND_ and the tenant from ORKMIND_; no argument selects the database or the identity. The operations are capabilities, get, query, history, receipts, head and ingest. Response states are ok, empty, unknown, withheld, forbidden, unavailable and conflict.
echo '{"schema":"orkmind.company-brain-api/v1","operation":"capabilities"}' | orkmind brain requestcontext mode: a citable package
A selection with mode context builds the orkmind. package on the server: the entities requested by id and the parents the grant lets you see, each with the complete source citation (authority, instance, reference, hash, version and location). Everything runs in one REPEATABLE READ, READ ONLY snapshot. Anything without a complete citation becomes a typed gap, with no content.
The digest is the sha256 of the package's canonical JSON, with no timestamp: the same state yields the same digest, and the receiver recomputes it. OrkMind cites; freshness against the source is computed by whoever holds the source. An OrkMind older than this mode answers brain..
entity.: missing, deleted or without theunknown getgrant.entity.: withheld by the ACL; only thewithheld idappears.citation.: the visible citation is not complete, so the item is left out.incomplete owner.,unresolved observed.andunknown recorded.: a cited item without a resolved owner or a timestamp.unknown
Append-only history
The history operation returns an entity's versions in sequence order, each with its origin: event, producer, cited source, factory cycle, recording time and the rolled_back flag. Nothing deletes or rewrites these versions; for a deleted entity, the tombstone is the last one.
It requires the history action, for humans only; without it, the answer is unknown. A grant that does not show the source field gets forbidden, because a version without an origin is not citable. Body fields follow the grant's fields.
echo '{"schema":"orkmind.company-brain-api/v1","operation":"history","payload":{"tenant_id":"exemplo","id":"proj-exemplo","limit":50}}' | orkmind brain requestWrites, migration and use by Orkastery
Only the service producer writes: ingest checks sequence, authorship, version and references and records projection, history and receipts in the same transaction; repeating the same event returns the same receipt. Administrative migration uses orkmind brain migration, with a hash-checked plan and rollback by compensation, never by restoring the whole database. The schema is created only by an explicit administrative operation; a query never migrates.
In Orkastery, ork brain context requests the context mode, checks the whole package and adds freshness against the local portfolio. Against an OrkMind without this mode, it builds the package the earlier way, with query and get, and says so in the package.