# Markitect Integration Flow

This document describes how Markitect should use flex-auth as its first
protected-system consumer integration.

## 1. Publish Resources

Markitect emits a `FlexAuthResourceManifest` for each knowledge base or
resource slice it wants flex-auth to authorize. The emitted manifest should use
the namespace in `docs/markitect-resource-namespace.md` and include:

- stable resource ids such as `document:internal-note`
- resource type and parent links
- path, labels, trust zone, owner, and durable backend metadata
- `metadata.flex_auth_contract: resource-registration-v0`
- `caring_profile: caring-0.4.0-rc2` when the emitter can provide it

flex-auth imports the manifest through `internal/markitect.ImportResourceManifest`.
The importer enriches resources with CARING scope and plane classification and
returns diagnostics when a resource type, trust zone, label set, or CARING
profile is missing or ambiguous.

## 2. Submit Check Requests

For one resource, Markitect submits `CheckRequest`:

```text
subject + action + resource + context + optional caring_context
```

For repeated checks, Markitect submits `BatchCheckRequest` with the same
subject/action/context and a resource list. Resource order is preserved in the
response.

Markitect should pass local frontmatter and backend metadata as resource
attributes when they affect policy:

- `labels`
- `trust_zone`
- `markitect_path`
- `frontmatter_visibility`
- `source_revision`
- `workflow_state`
- `freshness_seconds`
- `data_classes`

Subject roles and groups should be normalized into subject attributes or loaded
into the registry as subject/group/team manifests. CARING dimensions should be
attached as `caring_context` when Markitect already knows the intended
descriptor; otherwise flex-auth can derive descriptors from relationship facts.

## 3. Enforce Decisions

Markitect maps flex-auth decision envelopes into its gateway contract with
`internal/markitect.ToGatewayDecision`.

Expected effects:

- `allow`: render, answer, package, activate, export, or run workflow.
- `deny`: block the operation.
- `redact`: continue with returned obligations such as `mask_fields`.
- `audit_denied`: block or quarantine while preserving an audit-grade record.

Markitect should enforce obligations before exposing data. For example, a
`mask_fields` obligation must be applied before rendering or model use, and a
`record_context_activation` obligation must be logged when a context package is
activated.

## 4. Record Decision IDs

Every gateway operation should persist the flex-auth decision id alongside the
Markitect request id, workflow id, rendered artifact id, or export id.

At minimum, always record:

- denies
- redactions
- exports
- context package activations
- workflow runs
- support, break-glass, or other CARING exposure events

The local flex-auth JSONL log is suitable for local development. Markitect may
also write the same decision id into its own event log.

## 5. Explain Decisions

When users need an explanation, Markitect can call flex-auth `explain` or use
the decision id to retrieve the persisted envelope and project it with
`ToGatewayDecision`.

Explanations should preserve CARING language:

- subject relation and canonical role, for example `Customer Doer`
- scope, for example `Resource document:internal-note`
- plane, for example `Data`
- capability, for example `View` or `Export`
- exposure mode, for example `Masked`, `Plaintext`, or `Exportable`
- restrictions, conditions, and conformance findings

Example explanation:

```text
Customer Doer may View Data Plane resource document:internal-note because reader_group.
```

## Local Mapping Summary

| Markitect local concept | flex-auth field | CARING dimension |
| --- | --- | --- |
| frontmatter visibility | `resource.attributes.frontmatter_visibility` | Exposure mode hint |
| document labels | `resource.attributes.labels` | Scope and exposure hint |
| owner/steward | `resource.owner`, subject groups/roles | Canonical role and relation |
| workflow state | `resource.attributes.workflow_state`, request context | Lifecycle/condition hint |
| context freshness | `request.context.freshness_seconds` | Condition and conformance finding |
| export request | `action: export` | `Export` capability and `Exportable` exposure |

The examples in `examples/markitect/` are the executable contract fixtures for
this flow.