Compliance, finance & operations

Domain analyses and remediation routing. ComplianceService, FinanceService and OperationsService each ask the sovereign model plane to assess one domain, and all three return the same status, violations and audit-trail shape. ComplianceService also holds the operator-owned half of a remediation: who an order is addressed to, whether it was approved, and the standing routing table by finding category.

This page also defines the evidence-document types (citations, facts, findings, deadlines and seals) that remediation orders and twin action cards share.

Summary

Service	RPC	Kind	Purpose
ComplianceService	AnalyzeCompliance	Unary	Compliance status, violations and audit trail
ComplianceService	AssignRemediation	Unary	Address one remediation order
ComplianceService	DecideRemediation	Unary	Record the human decision on one order
ComplianceService	ListRemediationRoutes	Unary	List the routing table
ComplianceService	SetRemediationRoute	Unary	Route a finding category to a department
ComplianceService	DeleteRemediationRoute	Unary	Remove a category’s route
FinanceService	AnalyzeFinance	Unary	Financial posture findings
OperationsService	AnalyzeOperations	Unary	Operational health and risk findings

What an analysis reads

None of the three analyses reads a live data source. FACE has no mapping from a domain to one of the tenant’s connections and tables. The verdict rests only on the system_context you send and on the instance’s own configuration. Every response from the current server says so in live_data_note. To ground an analysis, put the relevant facts in system_context.

A model failure is not reported as a pass. When the model returns nothing usable, the status is Unable to Assess, with a spoken_response that says it is not a finding of compliance.

ComplianceService

Full name semantics.v1.ComplianceService.

AnalyzeCompliance

rpc AnalyzeCompliance(AnalyzeComplianceRequest) returns (AnalyzeComplianceResponse);

Kind: Unary.
Auth: Bearer session.
Errors: UNKNOWN if the compliance agent’s template cannot be loaded. Model problems are not errors: when the model plane is not configured, times out, or returns an empty or unparseable answer, the response has compliance_status: "Unable to Assess" and no violations.

The compliance agent is given the instance’s environment, the observed audit-logging behaviour, operator-declared settings (labelled as declarations, not evidence), and system_context. The model call has a time budget, 15 seconds by default.

Request: AnalyzeComplianceRequest

Shared by all three analysis RPCs.

Field	Type	Description
`system_context`	`string`	Additional context for the analysis, appended to the system state. This is the only caller-supplied evidence the analysis sees.

Response: AnalyzeComplianceResponse

Shared by all three analysis RPCs.

Field	Type	Description
`compliance_status`	`string`	`Pass`, `Warning`, `Fail`, or `Unable to Assess` when no assessment was produced. Other values come verbatim from the model.
`violations`	`repeated` `ComplianceViolation`	Findings, each in one sentence.
`audit_trail`	`repeated` `ComplianceAuditTrail`	Systems checked and their status.
`spoken_response`	`string`	A spoken-style summary. On `Unable to Assess` it says why.
`orders`	`repeated` `RemediationOrder`	The dispatchable form of the findings, one per violation. The current server derives no orders, so this list is empty.
`live_data_note`	`string`	The server’s sentence about which live data the analysis read. Currently it always says that none was read. Empty only from an older server.

AssignRemediation

rpc AssignRemediation(AssignRemediationRequest) returns (AssignRemediationResponse);

Kind: Unary.
Auth: Bearer session. The author is the verified session subject.
Errors: INVALID_ARGUMENT if order_id or assignment is missing, or the assignment names no department, service provider or contact. UNAUTHENTICATED if the session has no subject. FAILED_PRECONDITION if no remediation order has ever been derived on this instance. NOT_FOUND if the order id is unknown. INTERNAL if the assignment cannot be stored.

Addresses one order. Assignments are stored separately from the analysis, so they survive the next derivation. The author fields in the request are ignored and set by the server. Because the current server derives no orders, this RPC returns FAILED_PRECONDITION until orders exist.

Request: AssignRemediationRequest

Field	Type	Description
`order_id`	`string`	Required. `RemediationOrder.id`.
`assignment`	`RemediationAssignment`	Required. `department`, `service_provider` and `contact` are read. At least one must be set. Author fields are ignored.

Response: AssignRemediationResponse

Field	Type	Description
`assignment`	`RemediationAssignment`	The stored assignment, with the server’s author and timestamp. Display this, not your draft.

DecideRemediation

rpc DecideRemediation(DecideRemediationRequest) returns (DecideRemediationResponse);

Kind: Unary.
Auth: Bearer session. The decider is the verified session subject.
Errors: INVALID_ARGUMENT if order_id or dispatch is missing, or dispatch.state is empty or not one of DRAFT, APPROVED, REJECTED, SENT. UNAUTHENTICATED, FAILED_PRECONDITION, NOT_FOUND and INTERNAL as for AssignRemediation.

Records the human decision on one order. FACE sends nothing itself. SENT records that a person dispatched the order outside the platform.

Request: DecideRemediationRequest

Field	Type	Description
`order_id`	`string`	Required. `RemediationOrder.id`.
`dispatch`	`RemediationDispatch`	Required. `state` is required. `note` and `channel` are stored. Author fields are ignored.

Response: DecideRemediationResponse

Field	Type	Description
`dispatch`	`RemediationDispatch`	The stored decision, with the server’s author and timestamp.

ListRemediationRoutes

rpc ListRemediationRoutes(ListRemediationRoutesRequest) returns (ListRemediationRoutesResponse);

Kind: Unary.
Auth: Bearer session.
Errors: INTERNAL if the stored routing table is unreadable. While it is unreadable, every category reads as unrouted and new routes are refused.

Request: ListRemediationRoutesRequest

No fields.

Response: ListRemediationRoutesResponse

Field	Type	Description
`routes`	`repeated` `RemediationRoute`	Every route, by category, ascending.

SetRemediationRoute

rpc SetRemediationRoute(SetRemediationRouteRequest) returns (SetRemediationRouteResponse);

Kind: Unary.
Auth: Bearer session. The author is the verified session subject.
Errors: INVALID_ARGUMENT if route is missing, route.category is empty, or the route names neither a department nor a contact. UNAUTHENTICATED if the session has no subject. INTERNAL if the route cannot be stored.

Creates or replaces the route for one category. The category is matched exactly against a finding’s category. It is not a prefix or a pattern. Orders addressed through a route carry assignment.basis = OPERATOR_ROUTING_RULE, which is distinct from an order someone assigned individually.

Request: SetRemediationRouteRequest

Field	Type	Description
`route`	`RemediationRoute`	Required. `category` plus a `department` or `contact`. Author fields are ignored.

Response: SetRemediationRouteResponse

Field	Type	Description
`route`	`RemediationRoute`	As stored, with the server’s author and time.

DeleteRemediationRoute

rpc DeleteRemediationRoute(DeleteRemediationRouteRequest) returns (DeleteRemediationRouteResponse);

Kind: Unary.
Auth: Bearer session.
Errors: INVALID_ARGUMENT if category is empty. UNAUTHENTICATED if the session has no subject. INTERNAL if the route cannot be removed.

Deleting a category that has no route is not an error.

Request: DeleteRemediationRouteRequest

Field	Type	Description
`category`	`string`	Required. The category whose route to remove.

Response: DeleteRemediationRouteResponse

Field	Type	Description
`deleted`	`bool`	Whether a route for that category existed.

FinanceService

Full name semantics.v1.FinanceService.

AnalyzeFinance

rpc AnalyzeFinance(AnalyzeComplianceRequest) returns (AnalyzeComplianceResponse);

Kind: Unary.
Auth: Bearer session.
Errors: FAILED_PRECONDITION if no model plane is configured on the instance. UNAVAILABLE if the model plane does not answer. An empty, unparseable or empty-but-parseable answer returns compliance_status: "Unable to Assess".

Assesses the financial posture of the system state and system_context. Uses AnalyzeComplianceRequest and AnalyzeComplianceResponse. Findings arrive as violations.

OperationsService

Full name semantics.v1.OperationsService.

AnalyzeOperations

rpc AnalyzeOperations(AnalyzeComplianceRequest) returns (AnalyzeComplianceResponse);

Kind: Unary.
Auth: Bearer session.
Errors: The same as AnalyzeFinance.

Assesses operational health and risk. The request and response are the same as for AnalyzeFinance.

Messages

ComplianceViolation

Field	Type	Description
`category`	`string`	Area of the finding. Remediation routes match on this exactly.
`severity`	`string`	Severity, as the finding states it.
`description`	`string`	The finding in one sentence.
`related_rule_id`	`string`	The rule the finding relates to, if any.
`remediation`	`string`	Suggested remediation.

ComplianceAuditTrail

Field	Type	Description
`system_name`	`string`	System checked.
`status`	`string`	Its status.
`last_checked`	`string`	When it was checked, as reported.

RemediationOrder

A dispatchable remediation: what to do, to what specification, by whom, and the record behind every figure. Every value in a step’s specification is cited, and a step that would need an unmeasured figure is not emitted. A deadline appears only when a contract clause, SLA or statute in the data supplies it.

Field	Type	Description
`id`	`string`	Stable within an analysis: the rule id plus the subject, so assignments and decisions survive the next derivation.
`related_rule_id`	`string`	The rule behind the finding.
`category`	`string`	The finding’s category.
`severity`	`string`	`CRITICAL`, `HIGH`, `MEDIUM` or `LOW`, as the finding stated.
`subject_id`	`string`	What the order is about: a carrier, a column, a PO.
`summary`	`string`	The violation’s own sentence, unchanged.
`assignment`	`RemediationAssignment`	Who it is addressed to.
`steps`	`repeated` `RemediationStep`	The procedure, in order.
`specifications`	`repeated` `DocumentFact`	What the records say.
`citations`	`repeated` `Citation`	Where every figure came from.
`deadlines`	`repeated` `DocumentDeadline`	Deadlines with a cited authority.
`determinations`	`repeated` `DocumentFinding`	Findings as codes.
`narrative`	`DocumentNarrative`	Prose over the frozen fields.
`dispatch`	`RemediationDispatch`	The operator’s decision. Unset means nobody has decided. That is not a rejection, so display it as neither approved nor refused.
`seal`	`DocumentSeal`	Set at approval, never at derivation.

RemediationStep

Field	Type	Description
`ordinal`	`int32`	1-based position.
`instruction`	`string`	What to do, in the imperative, naming values.
`performed_by`	`string`	The role that performs it, when a record says so. Otherwise empty, never a guess.
`citation_ids`	`repeated string`	Citations for any figure the step names.
`specification`	`map<string, string>`	The specification to carry the step out to. Keys are stable codes, values are as read.
`verification`	`string`	How to check that it worked, against the same source.

RemediationAssignment

Field	Type	Description
`department`	`string`	A department in your organisation. Only an operator sets it: FACE has no org chart.
`service_provider`	`string`	An external provider, such as the carrier the finding is about. May be derived from a record.
`contact`	`string`	Email or desk, only when an operator supplied one.
`basis`	`string`	`DERIVED_FROM_RECORD`, `OPERATOR_ASSIGNED`, `OPERATOR_ROUTING_RULE` or `NOT_ROUTED`. `NOT_ROUTED` is the default. Display it as unrouted rather than hiding the block.
`assigned_by`	`string`	The verified subject, when operator-assigned. Server-set.
`assigned_at_unix`	`int64`	When it was assigned. Server-set.
`citation_ids`	`repeated string`	Citations for a provider derived from a record.

RemediationDispatch

Field	Type	Description
`state`	`string`	`DRAFT`, `APPROVED`, `REJECTED` or `SENT`. An empty string means no decision, which is a fourth state and not a synonym for `DRAFT`.
`decided_by`	`string`	The verified subject. Server-set.
`decided_at_unix`	`int64`	When it was decided. Server-set.
`note`	`string`	Why, in the decider’s words.
`channel`	`string`	How a `SENT` order left. Empty means the sending was not recorded.

RemediationRoute

Field	Type	Description
`category`	`string`	A finding category, matched exactly.
`department`	`string`	Department the category is routed to.
`contact`	`string`	Contact for the category.
`set_by`	`string`	The verified subject. Server-set.
`set_at_unix`	`int64`	When it was set. Server-set.

Evidence-document types

Remediation orders and twin action cards share these types. The platform’s rule is that everything except a narrative is determination: fixed arithmetic over cited records, never a model. A model may write only the narrative, and only from fields that are already frozen.

EvidenceDocument

A document a third party acts on, such as an adjuster, a carrier’s claims desk or a court. It assembles the file, shows what was read and proposes a next step. It does not underwrite, bind, settle or satisfy an obligation on anyone’s behalf.

Field	Type	Description
`kind`	`EvidenceDocumentKind`	Document kind.
`subject_id`	`string`	Your own identifier for the subject: a shipment, claim or customs entry. Also the chain key for the seal.
`reference`	`string`	The document’s own reference, where one exists.
`counterparty`	`string`	Who it is addressed to, or who owes.
`facts`	`repeated` `DocumentFact`	What the records say.
`findings`	`repeated` `DocumentFinding`	What was determined, as codes.
`citations`	`repeated` `Citation`	Where each figure came from.
`deadlines`	`repeated` `DocumentDeadline`	Computed deadlines.
`claimed_amount`	`optional double`	What the document asks for. Absent means not determined. See `absent`.
`exposure_amount`	`optional double`	Value at risk, not yet lost.
`units_short`	`optional int32`	Units short.
`units_damaged`	`optional int32`	Units damaged.
`absent`	`repeated` `AbsentFigure`	Why a figure is absent, when it is.
`narrative`	`DocumentNarrative`	Expression over the frozen fields.
`seal`	`DocumentSeal`	Set at approval. Unset on a pending card is correct.

Citation

Field	Type	Description
`id`	`string`	Citation id, for example `C1`, referenced by facts, findings and narrative.
`source_kind`	`string`	Record kind, for example `bol`, `invoice`, `po` or `reefer_reading`.
`source_id`	`string`	The record’s id in your own system.
`field`	`string`	Which field of the record.
`value`	`string`	The value as read, verbatim.
`connection_id`	`string`	Connection it was read through.
`lineage_record_id`	`string`	The lineage record of the extraction that read it, so the citation can be audited.
`observed_at`	`int64`	When it was observed, from the lineage record.
`perception`	`Perception`	Set only when a model read the value off a scanned document. Absent means a structured record.

Perception

Field	Type	Description
`outcome`	`PerceptionOutcome`	How the reading went.
`confidence`	`double`	The model’s own confidence. Never used as a truth threshold.
`model`	`string`	The model that read it.
`page_ref`	`string`	Where on the document.

DocumentFact

Field	Type	Description
`label_code`	`string`	Stable label code, for example `FACT_BOL_QUANTITY`. The client composes the label.
`value`	`string`	As read, or as computed.
`citation_ids`	`repeated string`	Never empty.

DocumentFinding

Field	Type	Description
`code`	`string`	Stable code, for example `OSD_SHORT`, `OSD_DAMAGED`, `RATECON_ACCESSORIAL_UNSUPPORTED` or `SLA_BREACH_CONFIRMED`. Render nothing for an unknown code, never the raw token.
`severity`	`string`	`CRITICAL`, `MAJOR`, `MINOR` or `INFO`.
`citation_ids`	`repeated string`	Never empty.
`operands`	`map<string, string>`	The numbers the code declares.

DocumentDeadline

A date computed from a record date by a named rule. It is an input for a person entitled to act, not advice. There is no “days remaining” field: compute it from due_unix when you render.

Field	Type	Description
`rule`	`string`	For example `CARMACK_NOTICE_9M`, `CARMACK_SUIT_2Y1D`, `COGSA_SUIT_1Y` or `CONTRACT_<clause>`.
`authority`	`string`	The cited authority, for example `49 U.S.C. § 14706(e)`.
`basis`	`string`	`delivery`, `should-have-been-delivered` or `disallowance`.
`from_unix`	`int64`	Start date.
`from_citation_id`	`string`	The record that supplied the start date.
`due_unix`	`int64`	Due date.

AbsentFigure

Field	Type	Description
`figure`	`string`	The figure’s field name, for example `claimed_amount`.
`reason`	`string`	`NO_BACKING_RECORD`, `NOT_STATED_ON_DOCUMENT`, `ILLEGIBLE`, `EXTRACTION_FAILED` or `NOT_YET_DETERMINABLE`.

DocumentNarrative

Field	Type	Description
`body`	`string`	The prose.
`authored_by`	`string`	`deterministic-template`, or the model id.
`figure_ids`	`repeated string`	Citation ids of every figure the body mentions.

DocumentSeal

Field	Type	Description
`algorithm`	`string`	For example `sha256-chain-v1`.
`content_hash`	`string`	Hash over the document’s canonical content.
`prev_hash`	`string`	The previous seal for the same `subject_id`.
`sealed_at`	`int64`	When it was sealed.
`signature`	`string`	Detached signature, when a signing key is configured.
`key_id`	`string`	Signing key id.

Enums

EvidenceDocumentKind

Value	Meaning
`EVIDENCE_DOCUMENT_KIND_UNSPECIFIED`	Not set.
`EVIDENCE_DOCUMENT_KIND_STATEMENT_OF_POSITION`	Paralegal and claims recovery.
`EVIDENCE_DOCUMENT_KIND_OSD_REPORT`	Over, short and damaged report.
`EVIDENCE_DOCUMENT_KIND_NOTICE_OF_INTENT_TO_CLAIM`	Notice of intent to claim.
`EVIDENCE_DOCUMENT_KIND_SUBROGATION_DEMAND`	Subrogation demand.
`EVIDENCE_DOCUMENT_KIND_FNOL`	First notice of loss (cargo insurance).
`EVIDENCE_DOCUMENT_KIND_CARGO_LOSS_SURVEY`	Cargo loss survey.
`EVIDENCE_DOCUMENT_KIND_WARRANTY_COMPLIANCE_AUDIT`	Warranty compliance audit.
`EVIDENCE_DOCUMENT_KIND_PRE_DEPARTURE_RISK_BINDING`	Not built. Pricing risk needs a rating basis, loss history and appetite that the platform does not hold. Never emitted.
`EVIDENCE_DOCUMENT_KIND_CLAUSED_EBOL`	Not built. No source carries the driver or receiver remarks that make up the clausing. Never emitted.
`EVIDENCE_DOCUMENT_KIND_RATE_CON_ACCESSORIAL_AUDIT`	Rate confirmation accessorial audit.
`EVIDENCE_DOCUMENT_KIND_MSA_SLA_COMPLIANCE_AUDIT`	MSA / SLA compliance audit.
`EVIDENCE_DOCUMENT_KIND_TEMPERATURE_EXCURSION`	Cold-chain temperature excursion.
`EVIDENCE_DOCUMENT_KIND_CHAIN_OF_CUSTODY_AUDIT`	Chain-of-custody audit.
`EVIDENCE_DOCUMENT_KIND_CUSTOMS_MANIFEST_EXCEPTION`	Customs manifest exception.
`EVIDENCE_DOCUMENT_KIND_PROCEDURE_DEVIATION_LOG`	Not built. A deviation log needs the customer’s written procedures, which no source carries. Never emitted.
`EVIDENCE_DOCUMENT_KIND_RETURN_DISPOSITION`	Disposition of a returned unit. Never invents a return identifier.
`EVIDENCE_DOCUMENT_KIND_SERVICE_DISRUPTION`	A service disruption stated by your own records, with the dwell counted from them.
`EVIDENCE_DOCUMENT_KIND_EQUIPMENT_LIMIT_APPROACH`	A channel trending towards a limit the feed itself states. A linear trend, not a prediction.

A client that meets an unknown kind should render the generic document shell, never the raw token.

PerceptionOutcome

Value	Meaning
`PERCEPTION_OUTCOME_UNSPECIFIED`	Not set.
`PERCEPTION_OUTCOME_READ`	The value was read.
`PERCEPTION_OUTCOME_NOT_PRESENT_ON_DOCUMENT`	The document does not carry the value.
`PERCEPTION_OUTCOME_ILLEGIBLE`	The value is present but illegible.
`PERCEPTION_OUTCOME_EXTRACTION_FAILED`	Extraction failed.

Analysis, posture & rules SQL