Governance Framework

The Team Technical Overview See it in Action

001 — Running today, and proven

The two-gate pipeline in production.

This is the system as it runs right now: enforcement by operating-system permissions and deterministic code, with the AI sandboxed between two human gates. Every claim below is backed by the automated test suite and live, on-disk verification.

How Portage Governs AI — the two-gate sovereignty pipeline

"No AI in Portage can read an unapproved contribution or publish anything — not because we ask it nicely, but because it doesn't hold the keys."

🔒Structural — enforced by OS permissions / deterministic code

✓Verified — tested AI behavior

IN — humans decide what the AI may read

MIDDLE — the AI, sandboxed

OUT — code decides what the public sees

Contribution

A teacher submits content via web form or CSV upload.

🔒

pending/ — quarantine

OS-locked. No AI can read this.

🔒

Human Gate ① — Approval

A named person reviews and approves

A named person reviews the full content and approves. Deterministic code, no AI. Signed + timestamped.

🔒

Sandboxed — the only place an AI acts

The AI (Hermes) compiles

The only place an AI acts — and only on approved content. Restricted by default.

✓

wiki/

Restricted + public pages.

🔒

Human Gate ② — Publication

Two keys must turn together

Two keys: the page is public AND a human signed this content. Deterministic export.

🔒

public-kb.json

Integrity-sealed. The assistant sees only this. Restricted knowledge is absent — not refused.

🔒

Public assistant

Answers only from the sealed public knowledge base.

🔒

How we proved it

4/4

Adversarial governance tests passed — non-leakage, the aggregation loophole, fail-closed on unmarked content, provenance-over-apparent-sensitivity. Each verified on disk.

Automated tests across export, gate, and API.

Live proof

A tampered export makes the assistant refuse to boot.

Live proof

A rogue AI-written "public" page is excluded and alarmed — the AI can't publish.

002 — From instruction to machine-readable rules

The principles never change. The enforcement matures.

Today's system proves the principles with operating-system permissions and a deterministic export: the AI cannot read what humans haven't approved, and cannot publish what humans haven't signed. The full framework below takes the next step — governance rules become machine-readable policy, evaluated by ordinary code on every request, and the AI is demoted to a drafter: it proposes, humans ratify, and it never decides who sees what.

Deliberately demoting probabilistic behaviour means access control never depends on how a model behaves — only on rules a community can read, version, and audit.

003 — The full framework

Community-authored policy, evaluated at runtime.

Four stages under one machine-readable policy: submission review, the governed wiki, mediated access, and publication. Each diagram expands its own terms — tap “Terms used” on any card.

System overview

A community-authored policy, evaluated at runtime, governs all four stages. Wiki data is served to every live audience, including anonymous/public, through per-request policy evaluation. Data leaves the enforcement boundary only via the publication pipeline.

Data governance policy

Machine-readable rules, versioned · community-edited via policy builder · hot-reloaded by the PDP

Submission review

Intake API → pending store (no agent read access) → policy-routed human review → deterministic approval validation → approved store.

→

Governed wiki

Compile worker (LLM) drafts pages; human ratification required. Pages stored with governance metadata; access computed per request, never stored.

→

Mediated access

All live serving: teacher/student app, authenticated APIs, public web (audience = anonymous). PDP evaluates every request. Revocation immediate.

Publication (boundary-crossing only)

Exports, bulk API consumers, third-party hosting: any release producing a copy the PDP no longer mediates. Explicit publisher act, per-page policy check, signed versioned artifact, forward-only revocation.

Audit log (append-only). Submissions, reviews, compilations, ratifications, per-request access decisions with matched rule ids and policy version, publications, revocations. Community-readable, service-writable.

Terms used in this diagram

Enforcement boundary

The perimeter within which every read of wiki data is mediated by the policy engine. Publication is defined by crossing it.

PDP (policy decision point)

Evaluates policy rules against subject, resource, and context; returns allow/deny. Default deny; deny-overrides.

Hot-reload

A committed policy edit applies to the next request, with no deploy or restart.

Governance metadata

The per-page record of audience tags, context, and provenance that rules are evaluated against. Access is computed per request, never stored on the page.

Ratification

The human final-approval step that makes a drafted page part of the wiki store.

Mediated access

Release mode where every read is policy-evaluated through the PEP; revocation is immediate and total.

Publication

Release mode producing a copy the PDP can no longer mediate; requires the publication pipeline; revocation is forward-only.

Audit log (append-only)

Tamper-evident record of every governance-relevant event. Entries can be added, never modified or removed.

Ingest path

Submission to approved store. The compile worker has no read access anywhere on this path until the approval validator moves content forward.

Contributor client→ Intake APIwrites only→ Pending storeno agent read perms→ Review routerreads reviewer roles from policy→ Reviewer clientapprove / edit / reject→ Approval validatordeterministic field check, fail-closed→ Approved store

Deterministic enforcement Human actor Data store Service / process

Terms used in this section

Intake API

Write-only entry point for submissions in any format; it cannot read back or modify stored content.

Pending store

Storage for unreviewed submissions. The compile worker has no read permission on it; the boundary is enforced by the platform, not by instruction.

Review router

Service that reads reviewer roles from the policy per content type and notifies the corresponding reviewers.

Approval validator

Deterministic code that checks approval fields (approver, timestamp, exact boolean state) before moving content from pending to approved.

Fail-closed

Any error state (missing field, malformed record, ambiguous status) resolves to deny: the item stays in pending, never defaults forward.

Approved store

Storage for content carrying a validated human approval record. The only content source the compile worker can read.

Compile path

Approved content to indexed wiki. The LLM drafts; a human ratifies. No page enters the wiki store without both.

Approved storeread-only mount→ Compile worker (LLM)drafts pages + change report→ Final approverratifies drafts against change report→ Wiki storepages + governance metadata, versioned→ Indexermetadata carried into index→ Retrieval indexmetadata-filterable

Human actor Data store LLM component Service / process

Terms used in this section

Compile worker

The LLM-based process that drafts wiki pages and change reports from approved content. Proposes only; cannot ratify, cannot publish.

Change report

The compile worker's machine-generated summary of what it created or modified, reviewed during ratification.

Ratification

The human final-approval step that makes a drafted page part of the wiki store.

Governance metadata

The per-page record of audience tags, context, and provenance that policy rules are evaluated against at request time.

Provenance

The recorded chain from a page back to its source submissions, contributor, compiling worker and model, and approving reviewer.

body_hash / versioning

Each page version carries a content hash, so decisions and artifacts pin exactly which text they refer to.

Indexer

Builds the searchable index from the wiki store, carrying governance metadata alongside text.

Retrieval index

The index queried at serve time; metadata-filterable so non-permitted content is excluded before ranking.

Serve path (per request, mediated access)

Covers every live audience: teacher/student app, authenticated APIs, and public web pages served as audience = anonymous. Every request is evaluated; no cached views.

Clientapp / API / public web→ Gatewayauthn → subject attributes→ PEPenforcement point⇄ PDPevaluates rules, default deny→ Filtered retrievalpermitted-set predicate as index filter→ LLM inferenceprovider-agnostic, permitted chunks only→ Output filterdenylist + citation check→ Responseaudit written with rule ids + policy version

Deterministic enforcement Human actor LLM component Service / process

Terms used in this section

Mediated access

Release mode where the consumer reads through the PEP and every request is policy-evaluated; revocation is immediate and total.

Subject attributes

Facts about the requester (role, community, groups, enrollments, age band) resolved from the identity store, never from the request payload.

PEP (policy enforcement point)

The component on the request path that calls the PDP and enforces its decision. The PDP decides; the PEP blocks or permits.

PDP (policy decision point)

Evaluates policy rules against subject, resource, and context; returns allow/deny plus obligations. Default deny; deny-overrides.

Permitted-set predicate

The PDP's output for a request, expressed as a condition over page metadata and compiled into the retrieval query's filter.

Filtered retrieval

Executing the search with the predicate as a metadata filter, so non-permitted content is excluded before anything is loaded into memory.

Model-agnostic

Any LLM provider works because no access control depends on model behavior; the model only ever receives permitted content.

Output filter

Deterministic post-generation checks; failure blocks the response and is logged.

Denylist

Terms derived per request from the content this requester was denied, scanned for in the output as a leak heuristic.

Citation check

Every citation in the response must resolve to a chunk actually provided in context for this request.

Policy version

Hash-pinned identifier of the rule set in force, recorded in every audit entry so decisions are reconstructable.

Hot-reload

A committed policy edit applies to the next request, with no deploy or restart.

Runtime request path

The sequence view of the serve path: what happens per request, in order. Applies to every mediated audience including anonymous. No cached views.

Authenticate, resolve subject attributes

Session → {role, community, groups, course_enrollments, age_band}. Attributes come from the identity store, not from the request payload. Anonymous requests carry empty attributes.

PDP evaluates policy

evaluate(subject, action=access, resource_class, context) against the current policy version. Output is a permitted-set predicate over page metadata. Deny-overrides; no matching rule → deny; unmarked metadata → deny.

Filtered retrieval

The predicate is compiled into a metadata filter on the index query. Non-permitted chunks are excluded before ranking; nothing outside the permitted set is loaded into memory for this request.

Context assembly

Selected chunks recorded by page_id + version for the audit trail and citation check. Provenance constraints from matched rules applied here.

LLM inference

Prompt = system instructions + permitted chunks + user query. Provider-agnostic; the model receives only step 3 output, so trust in model behavior is bounded to phrasing, not access control.

Output filter

Deterministic post-checks: denylist terms derived from the excluded set for this request; citations must resolve to chunks provided in step 4. Failure → response blocked, logged.

Respond + audit write

Audit record: subject, decision, matched rule_ids, chunk ids and versions, policy_version hash, request id.

Policy hot-reload. A committed policy edit applies to the next request. No deploy, no restart.

Latency budget. Attribute lookup, rule evaluation, and metadata filtering are index-level operations, low single-digit ms against inference at hundreds of ms.

Fail-closed everywhere. PDP unreachable, policy unparseable, metadata missing: the request is denied, not defaulted open.

Aggregation mitigation. Provenance constraints (step 4) plus excluded-set denylist (step 6). Inference-level aggregation prevention is an open problem industry-wide; scoped as mitigation.

Terms used in this diagram

Subject attributes

Facts about the requester resolved from the identity store, never taken from the request payload.

Identity store

The system of record for subject attributes; security-critical because attributes drive access decisions.

Permitted-set predicate

The PDP's output for a request, a condition over page metadata compiled into the retrieval filter.

Chunk

The unit of retrieval: a passage of a wiki page carrying its parent page's id, version, and metadata.

Context assembly

Building the model's input from retrieved chunks, recording each chunk's page id and version, applying provenance constraints.

Provenance constraints

Rules restricting derived content by the visibility of its sources, so restricted material does not launder into permitted output.

Denylist

Terms derived per request from the content this requester was denied, scanned for in the output as a leak heuristic.

Citation check

Every citation must resolve to a chunk actually provided in context for this request.

Policy version

Hash-pinned identifier of the rule set in force, recorded in every audit entry.

Fail-closed

Any error state resolves to deny, never to open.

Publish path (boundary-crossing only)

Sole path producing copies outside the enforcement boundary: exports, bulk API consumers, third-party hosting. Live serving to any audience is the serve path, not this one.

Publisher clientrole defined in policy→ Publication serviceauthz via PDP, per-page vs target channel→ Snapshot buildercanonical serialization, pinned versions→ Signerdetached signature, private key in KMS→ Artifact registryartifact@vN, immutable→ Distributionsignature verified on load; forward-only revocation

Deterministic enforcement Human actor Data store Service / process

Terms used in this section

Enforcement boundary

The perimeter within which every read of wiki data is mediated by the policy engine. Publication is defined by crossing it.

Publication

A release producing a copy the PDP can no longer mediate. Requires this pipeline; revocation is forward-only.

Channel

The mechanism reaching an audience. The channel's technical properties determine mode; users never choose between mediated and publication.

Snapshot

The page set selected for publication, serialized at pinned versions with a manifest of page ids, versions, and content hashes.

Canonical serialization

A deterministic byte encoding: same input, byte-identical output, so hashes and signatures are reproducible.

Detached signature

A signature stored separately from the data, produced with a private key. Distinct from a hash inside the file, which anyone who can write the file can recompute.

KMS / key custody

The key management service holding the private signing key, accessible only to the publication service role. Custody is what makes signatures unforgeable by other components.

Artifact registry

Immutable, versioned store of published artifacts. Corrections are new versions; registry plus audit log enumerate the entire exported surface.

Signature verification on load

Every consumer checks the signature against the public key before serving; failure means refuse to serve.

Forward-only revocation

A revoked version stops being served and the act is audited, but copies already outside the boundary persist.

Publication pipeline

The sequence view of the publish path. Sole path outside the enforcement boundary; applies only to channels producing a copy the PDP no longer mediates. Live serving to any audience, including anonymous/public, is the runtime request path, not this one.

Publish request

Initiated by a subject holding the publisher role defined in policy. Payload: page ids + target channel. Cannot be triggered by metadata state, a schedule, or the compile worker. Mode is derived from the channel, not selected by the user.

PDP authorization

evaluate(subject, action=publish, resource=page_set, channel). Per-page check against the target channel's audience: a page whose rules exclude that audience cannot be included regardless of who asks.

Snapshot build

Canonical serialization of the page set at pinned versions. Deterministic: same input → byte-identical output. Includes manifest of page_id + version + body_hash.

Sign

Detached signature over the snapshot. Private key in KMS, accessible only to the publication service role. Consumers hold the public key only; write access to storage does not confer the ability to forge a valid artifact.

Artifact registry

Stored as artifact@vN, immutable, named per channel. Corrections are a new version, never an edit. Registry entry links the audit record of the publish decision.

Distribution

The channel serves the artifact. Every consumer, including our own endpoints, verifies the signature before loading; verification failure → refuse to serve.

Revocation (forward-only)

A policy-defined role marks vN revoked; distribution stops serving it; the act is audited. Copies already outside the boundary persist; consumers are notified where the channel has a mechanism.

Failure containment. Compromise of the wiki store or a misbehaving compile worker cannot produce a published artifact: steps 2 and 4 both sit between internal state and release, one enforcing policy, one enforcing key custody. The exported surface is exactly the set of signed artifacts, enumerable from the registry and audit log.

Terms used in this diagram

Publisher role

A policy-defined role authorizing publish requests; publication cannot be initiated by services, schedules, or the compile worker.

Snapshot

The page set selected for publication, serialized at pinned versions.

Canonical serialization

Deterministic byte encoding: same input, byte-identical output, so hashes and signatures are reproducible.

Manifest

The artifact's contents list: each included page's id, version, and body_hash.

Detached signature

A signature stored separately from the data, produced with a private key. Distinct from a hash inside the file, which anyone who can write the file can recompute.

KMS / key custody

The key management service holding the private signing key, accessible only to the publication service role.

Artifact registry

Immutable, versioned store of published artifacts; with the audit log, it enumerates the entire exported surface.

Signature verification on load

Every consumer checks the signature against the public key before serving; failure means refuse to serve.

Forward-only revocation

A revoked version stops being served and the act is audited, but copies already outside the boundary persist.

Mode derivation

The channel determines whether the mediated or publication machinery applies; users cannot route around the pipeline by mislabeling.

Release model: mediated access vs publication

Enforcement boundary · PDP mediates every read

Wiki storepages + metadata→ PEP / PDPper-request evaluation→ Teacher / student appauthenticated audiences Authenticated APIper-call policy check Public web pagesaudience = anonymous, served live

Revocation: immediate and total. Policy edit applies to the next request.

copy crosses the boundary → publication pipeline required

Outside the boundary · PDP can no longer mediate

Downloadable exportsdatasets, backups handed over Bulk API consumerspartner ingests and stores Third-party hostingstatic copies elsewhere

Revocation: forward-only. Stop serving vN; existing copies persist. Hence: explicit publisher act, per-page policy check, signed versioned artifact, audit.

Community intent	Audience	Channel	Mode
Students in course X use the tutor	enrolled students	app, runtime	Mediated
Make selected pages public on our site	anonymous	web, served live	Mediated
Let a school board query via API	named org, authenticated	API, per-call	Mediated
Release a dataset to researchers	named org	export file	Publication
Open dataset for anyone to download	anonymous	artifact registry	Publication

Terms used in this diagram

Audience

A class of readers defined in policy by subject attributes. Anonymous/public is an audience with empty attributes, not a special state.

Channel

The mechanism through which content reaches an audience: app, live web, per-call API, export file, artifact download.

Grant

A policy rule connecting a content scope to an audience via a channel. The unit the community creates in the policy builder.

Mode derivation

Mediated vs publication is determined by the channel's technical properties, never selected by the user.

Mediated access

The consumer reads through the PEP; every request is policy-evaluated; revocation is immediate and total.

Publication

A release producing a copy outside the enforcement boundary, which the PDP can no longer mediate; revocation is forward-only.

Enforcement boundary

The perimeter within which every read is mediated. Defines the scope of continuous, reversible control.

Revocation, immediate vs forward-only

Mediated grants stop at the next request after a policy edit; published artifacts stop being served but existing copies persist.

Data model

wiki page (metadata)

id: page uuid
version: int
body_hash: sha256
provenance:
  source_ids: [submission ids]
  contributor: member id
  compiled_by: worker id + model
  review: {approver, ts}
audience: [role / group tags]
context: {community, course,
  seasonal / ceremonial flags}
access: restricted # only value;
  release is computed per request
  or per publish by the PDP,
  never stored here

policy rule (grant)

rule_id: string
effect: allow | deny
action: access | publish
subject: {role, community,
  group, age_band}
resource: {audience tags,
  context match, provenance
  constraints}
channel: app | web | api |
  export | registry # mode
  (mediated vs publication) is
  derived from the channel
conditions: {time window,
  seasonal flag, enrollment}
obligations: [audit, redact]
# deny-overrides; no match →
# deny; unmarked → deny
policy_version: semver + hash

audit record (append-only)

ts: rfc3339
actor: subject id | service id
action: submit | route | review |
  compile | ratify | access |
  publish | revoke
resource: id + version
channel: where applicable
decision: allow | deny
rule_ids: [matched rules]
policy_version: hash at
  decision time
request_id: correlation id
# community-readable;
# service-writable only

Every decision is reconstructable: the audit record pins the policy version and matched rules, page metadata pins provenance and review, and body_hash pins content. No decision depends on state that is not versioned.

Terms used in this diagram

Governance metadata

The per-page record of audience tags, context, and provenance that rules are evaluated against.

Audience tags

Metadata naming which audiences a page's rules may address, matched against grants at decision time.

Context (metadata)

Conditions attached to a page (community, course, seasonal or ceremonial flags), matched against the request's context.

Provenance

The recorded chain from a page back to its sources, contributor, compiling worker and model, and approving reviewer.

access: restricted

The only stored access value. Release is always computed by the PDP; a page-level toggle does not exist.

Grant (rule)

A rule connecting a content scope to an audience via a channel, for a given action. The unit created in the policy builder.

action field

Distinguishes access rules (evaluated per request on the serve path) from publish rules (evaluated in the publication pipeline).

channel field

Names the release mechanism; the system derives mediated vs publication mode from it, so users cannot select the wrong pipeline.

Deny-overrides / default deny

If no rule matches, deny; if both allow and deny match, deny wins.

Decision reconstruction

Any past decision can be re-derived from the audit entry's policy version, matched rule ids, and pinned page versions.

Verification architecture

Testing mechanisms, not achieved results. Because enforcement is deterministic code, the four adversarial governance cases become automated assertions on gate outputs, runnable in CI on every change, rather than one-time manual inspection of model behavior.

Deterministic: a pass is a property of the code, repeatable Probabilistic: measured rates, never guarantees

Deterministic · CI on every change

Adversarial governance suite

The four named cases as automated tests against the PDP and retrieval filter: non-leakage (restricted chunks absent from retrieval output for unauthorized subjects), aggregation loophole (provenance constraints exclude derived content), fail-closed on unmarked content (missing metadata → deny), provenance over apparent sensitivity (decisions follow metadata, never content heuristics).

Asserts on: gate output, not model output.

Deterministic · property-based

Policy engine property tests

Generated malformed inputs (broken policies, corrupt metadata, contradictory rules, forged subject attributes in payloads) fed to the PDP; every failure path must resolve to deny. Full deny-overrides matrix: for any allow/deny rule pair, deny wins.

Asserts on: evaluate() return values across generated input space.

Deterministic · scheduled re-runs

Canary content, end to end

Synthetic pages carrying unique tokens planted at each audience/context tier. Scripted queries across subject profiles (student, teacher, anonymous, cross-community) assert token absence at three layers: retrieval output, assembled model context, and final response. Re-run on a schedule against staging and production, not once.

Asserts on: token absence per layer, per profile, per run.

Deterministic · cryptographic

Publication integrity tests

Mutate artifact bytes → signature verification fails → distribution refuses to serve. Recompute the content hash without the signing key → verification still fails, distinguishing this from a hash-in-file check. Publish authz denial cases: a page excluding the target audience cannot enter a snapshot regardless of requester.

Asserts on: verification outcome and serve refusal.

Deterministic · invariant checks

Audit completeness and replay

Invariant: every served response correlates to an audit record carrying matched rule ids and policy version. Sampled decision replay: re-evaluate logged decisions against the pinned policy version and page versions; the outcome must reproduce.

Asserts on: log/response correlation and replay equality.

Deterministic · demonstrable live

Policy-to-behavior demonstration

Scripted sequence: query returns canary content → policy edit removes the grant → identical query on the next request returns nothing, with both decisions visible in the audit log. Same mechanism demonstrates immediate revocation of a mediated grant.

Asserts on: behavior change across one policy commit.

Probabilistic · measured, not guaranteed

LLM behavior evaluations

Red-team prompt sets (injection attempts via user queries and via approved content, restricted-topic probing, phrasing manipulation) run against the full serve path, reporting pass rates over repeated runs. This layer is defense in depth: access control does not depend on it, because the model never receives non-permitted content. Failures here degrade phrasing quality, not confidentiality of unretrieved content.

Reports: pass rates per category per model, tracked across versions.

Terms used in this diagram

Deterministic test

Same input always produces the same result; a pass is a property of the code, repeatable in CI.

Probabilistic evaluation

Measures model behavior over repeated runs; reported as rates, never as guarantees.

CI (continuous integration)

Automated test execution on every code or policy change; a failing gate blocks the change.

Property-based testing

Tests generated over an input space rather than hand-picked cases, asserting an invariant (here: all failures resolve to deny).

Canary token

A unique synthetic string planted in test content; its appearance anywhere it should not be is unambiguous evidence of a leak.

Decision replay

Re-evaluating a logged decision against its pinned policy and page versions; the outcome must reproduce exactly.

Red-team prompt set

A maintained collection of adversarial inputs, including injection attempts embedded in approved content, run against the full request path.

Staging vs production runs

Canary suites run against a staging replica on every change and against production on a schedule, so verification reflects the deployed system.

Looking forward

We haven't partnered with a community yet — we're building this so we can.

If you lead a Nation, school, or organization and want a hand in shaping what this becomes — from governance to curriculum — we'd welcome the conversation.

Start a Conversation →

We acknowledge Portage operates on the traditional territory of the Kanien’kehá:ka (Mohawk).

Follow along