flex-auth/docs/markitect-integration-flow.md

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:

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:

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.