Auditability & lineage
FACE keeps two different records. The audit log records security-relevant events: who did what, and which control refused what. The lineage log records data movement: which source was read, what shape came back and where it went. Neither record contains the data itself.
Audit logging
Always on
Audit logging is always on, and that is a property of the code, not a
setting. extractors.RecordAuditLog runs unconditionally, and no code path
disables it. The environment variable ENFORCE_AUDIT_LOGGING gates nothing (see
Compliance posture).
No record is dropped silently. Records normally go through an in-process actor. If that actor failed to start, the hook is never installed and records are written synchronously. If a send to the actor fails later, FACE switches to synchronous writes from then on, says so once in the log, and loses no record.
What a record contains
Each audit record is structured JSON with a timestamp, an event type, an actor ID, a target ID and a details map.
- Actor and target identifiers are hashed with SHA-256 before they are
written. The hash is deterministic, so an assessor can still group events by
actor without the log exposing the raw identifier. The system actor
SYSTEMis recorded as is. - Refusals are recorded. Guardrail refusals include the rule ID, severity,
category, compliance tags and the action
PROMPT_REJECTED. Voice-line refusals record the reason and the control that fired, but never the caller’s words. An agent email downgraded to a draft records the recipient only as a hash.
Where records go
FACE writes audit records to its standard output as structured JSON, beside its OpenTelemetry-shaped application logs. The platform’s log pipeline collects them from there.
Request logging
The unary request interceptor logs only the method name and the request size in bytes. Request bodies are never logged, because they carry prompts, data rows and document content. Personal data is masked before it is written to logs and audit records.
Decision authority and the decision log
How much authority an action needs
Before an approved action runs, FACE evaluates a decision-authority policy on the stored card, in the server, before any side effect. The policy is versioned JSON. Each rule can match on the side effects the card would perform (email, calendar, ERP update, evidence seal), its monetary value and currency, safety or regulatory flags, its business domain and the approver’s role. The answer is a tier:
| Tier | What it means |
|---|---|
| ADVISORY | Never executed. The card is advice; it can be rejected, not approved. |
| GUARDED | One named, attributed approver. This is the default when no rule matches. |
| DUAL | Two different named approvers. The same person cannot approve twice, and a service account cannot give either approval. |
| DENY | Refused. The card can be rejected, not approved. |
| AUTONOMOUS | May run with no approver. Only an explicit rule produces it, and a safety or regulatory flag lowers it back to GUARDED. |
When several rules match, the most restrictive tier wins, so rule order cannot
let a permissive rule hide a restrictive one. The shipped default
(face-default-2026-10-01) asks for a second approver for actions worth 10,000
or more in the card’s own currency, and for safety- or regulation-relevant
cards. Everything else needs one approver.
Operators replace the default with FACE_AUTHORITY_POLICY_FILE. A file that
cannot be read or parsed does not fall back to the default: every approval is
refused until it is fixed. For example, this policy asks for two approvers above a
value the operator chose and for safety or regulatory cards, and adds an
AUTONOMOUS rule for agent mail to allowlisted recipients. Mail the
agent composes is nevertheless never sent on its own: such a rule is evaluated
and recorded in the audit trail, and the mail is drafted in the operator’s
mailbox for a person to read and send. Nothing a model proposes leaves the
platform without a person approving it.
{
"version": "policy-v1",
"rules": [
{"id": "dual-high-value", "tier": "DUAL", "min_value": 25000},
{"id": "dual-safety-regulatory", "tier": "DUAL", "any_flags": ["safety", "regulatory"]},
{"id": "autonomous-allowlisted-email", "tier": "AUTONOMOUS",
"actions": ["email"], "domains": ["twins_agent"],
"conditions": [{"attr": "resource.recipient_allowlisted", "op": "eq", "values": ["true"]}]}
]
}Unknown fields are refused when the policy loads, so a misspelt bound cannot silently widen a rule. Every decision records the policy’s SHA-256.
Actionable Twins shows each card’s tier, the rule IDs that decided it and why. A DUAL card shows “1 of 2 approvals” and who approved. ADVISORY and DENY cards show no approve control. The server enforces all of this whatever the client shows.
The decision log
Every decision is written to an append-only decision log before anything runs, and its outcome (executed, refused, failed, recorded, or awaiting a second approver) follows as a second record. A record holds the decision and card IDs, the approvers as verified identities, the policy version, its SHA-256 and the matched rules, the judging ladder’s verdict, the model and prompt-template digest when a model wrote the card, the cited input rows and a timestamp. A field FACE does not know is left empty, never filled in.
Records are hash-chained: each holds the SHA-256 of its own canonical JSON and the hash of the record before it. Admins can read the log, and the server’s verification of the whole chain, on the Admin page opened from Settings › Account. Verification reports the first record that was modified, removed or moved. If the decision log cannot be written, the action does not run.
Observed data lineage
The lineage recorder captures observed data movement, one immutable record per event. It does not describe lineage from a schema. It records reads that actually happened.
Where it is captured
- Every tabular connector.
extractors.ConnectorForTypereturns every connector wrapped in a lineage decorator. All connectors are covered with no per-connector code. - Camera ingests. Frames pushed by a camera do not pass through the connector seam, so the ingest path records them itself: one record per ingest on every return path, failures included.
- Deliveries. The connector does not know where its result will go, so the calling pipeline attaches the destination afterwards. It does so only on the branch where the rows actually landed.
What a record contains
A lineage record carries structure only. Every field is an identifier, a structural name, a count, a duration or a fingerprint:
| Field group | Contents |
|---|---|
| Kind | extraction (a source was read), delivery (a result landed somewhere) or discovery (a source described its own catalogue, and no business data moved) |
| Source identity | Connection ID, connection name, connector type, environment, runner. Taken from the connection’s labels only, never from its configuration or credentials. |
| What was asked | A literal-free query shape plus its fingerprint |
| What came back | Column names and a row count |
| Outcome | ok, empty or error. An error is kept as a closed-set error class plus a SHA-256 fingerprint of the driver message. The message itself is never stored. |
| Destination | Kind, ID and name of the sink (delivery records only) |
| Correlation | Record ID, reference to the originating extraction, trace ID, timestamp, duration |
Never recorded: cell values, sample rows, result bodies, driver error text,
credentials or connection configuration. The recorder is never given the result
body, and no field on it could carry one. TestNoResultValuesReachAnyLineageRecord
fills every value-shaped input with unique sentinel strings and asserts that none
of them survives into a record or into the encoded file. Every field has a
length limit, so a record’s size is bounded and measured.
Where it is stored
Lineage records are append-only Avro files in the object store, partitioned
by UTC day. The object store seals every object it writes (see
Encryption at rest). LineageService.GetSourceActivity reads
this log. The FACE app does not show it today; it is an API call.
Scope of these controls
- Compare the decision log with the audit stream. Every new chain head is also written to the audit stream, where it can be compared with the log. Timestamps are the server’s clock.
- Retention belongs to the log pipeline. FACE emits audit records to standard output. How long they are kept, who can read them and how they are protected once written are properties of the log pipeline your deployment runs.
- Hashing is pseudonymisation, not anonymisation. Anyone who already knows an identifier can compute its hash and find that identifier’s events.
- A camera ingest records zero rows. A camera sends frames, not rows. The record therefore calls the ingest an extraction with a row count of zero, and carries no frame count.
- A query fingerprint is not the query. It proves two reads had the same shape. It cannot reconstruct the values that were used.