What leaves your machine

Nothing leaves until preparation decides

You choose the goal and the evidence your agent may use. Local preparation then selects the minimum permitted data and makes a working copy in your environment. It applies your field rules, checks what remains and shows what would be transferred.

Check the records, then the complete request. prepareRecords uses your schema, field policy and configured detectors to prepare and re-scan the records. Your integration separately inspects and re-scans added instructions, schemas, examples and metadata—and the complete request—in your controlled environment before sealing.

Supply the scoped alias handle with the request. The helper does not automatically understand or approve an arbitrary repository or folder.

A support-ticket example, before and after. This fictional example uses illustrative values only; it contains no real person or credential.

The alias value in this table is illustrative, not a production token. If a free-text name cannot be matched to exactly one confirmed entity, preparation does not guess; it records a review item and redacts that occurrence.

Your existing agent keeps the goal and project context, chooses the minimum permitted evidence, and authors the task instructions, rubric or review rule, expected output and checks. The Kit performs supported local preparation, fit and sealing; Lithi processes only the approved work; the agent checks the returned evidence. Preserve syntax, dependencies, semantic groups and stable identities when selecting context, and keep any protected reverse map outside the reasoning context.

For code work, select the permitted files and supporting evidence first. The Data module's decodeCodeFile reads a supported UTF-8 source file into a source-linked unit; codeUnitsToDetectorInput adapts those units to detector input without scanning them itself. The caller runs the configured checks and preserves the callers, types, dependencies and test evidence needed to judge the change. See Lithi Code & Tests and the Kit helper reference for that preparation path.

Only an eligible prepared copy can become ciphertext bound for Compute. Renaming a source, changing its profile label, or submitting it again does not bypass a blocked or unresolved condition.

Three decisions, never a silent fallback

Every preparation run ends in exactly one of three decisions: blocked, review_required, or eligible.

Your records
     ↓
Prepare a copy locally
     ↓
Inspect, transform and re-scan
     ↓
blocked / review_required / eligible

eligible is a preparation result, not transfer approval or execution approval.

• Blocked. A secret or credential always stops the run. A rejected review item also stops it, and a coverage gap stops it when the policy sets coverage_gap_mode: block. The prepared copy is withheld, and the original input never becomes a fallback.
• Review required. Preparation produced a copy that stays local, but at least one condition — an unresolved name match or a field kept without inspection — needs your decision. Nothing can be sealed yet.
• Eligible. Every required check cleared and any review items were resolved. Only this decision produces the commitment that sealing can bind to.

An ambiguous or conflicting same-name match never merges records. Preparation leaves that mention unresolved and uses a fixed redaction in the prepared copy until you resolve the review item. A detector gap is also not a clean result: not inspected and no findings remain separate.

From a field policy to an approved sealed input

The TypeScript kit's prepareRecords helper receives the source schema, records, field policy, scoped alias handle, and the configured content and secret checks. It returns the prepared derivative, a decision, and protected local evidence. The source schema, detailed findings, detector reports, and reverse map stay in your environment; the agent-facing summary exposes only closed reason codes, counts, and opaque review references.

The local workflow checks separate parts of the request. After prepareRecords checks the derivative records, the caller validates prompt and instructions, schemas, examples, context and metadata, then re-scans the complete composed request. A detector that does not support a field, fails or reports incomplete coverage leaves a coverage gap; it is never silently treated as clean. A secret finding blocks the run. Fix the source or policy and prepare again; preparation never falls back to the original or an unscanned copy.

Only an eligible result can produce preparedBinding, the commitment that binds the prepared bytes, effective policy, coverage and review decisions to sealing. preparedBinding does not approve a transfer or job. The local workflow can then use sealBlocks to create encrypted blocks and the content-free manifest; transfer approval and the later bindApproval → submitApprovedJob path remain required before the sealed input is sent or work is submitted. Transfer approval authorizes moving the sealed input to its named destination; execution approval admits paid work. An eligible retry or accepted-result replay covered by the approved job or policy does not ask for either approval again.

This prepared copy is the input to the next privacy boundary. If the batch contains several atomic groups, Lithi's spread policy assigns sealed pieces across owners and counts every group an owner can reach through production, verification, combining, retries, or hedges. Preparation can reduce what each piece contains; it does not choose the pieces or make the remaining text unreadable to the Mac processing it. The 25% cap used in the sharding example illustrates the calculation, not a universal default.

Coverage is tracked, not just findings

A detector that crashed, timed out, inspected only part of a field, or does not support a field is a coverage gap — never read as "clean." "No findings" and "not inspected" are different outcomes, and preparation keeps them distinguishable so a genuine clean pass is never confused with a check that never actually ran. Depending on the policy, a gap requires your review or blocks the run.

The re-scan catches what transformation adds

Before anything is sealed, the prepared derivative and the complete composed request are scanned again with the independent secret and content checks. A transformation or composition step can introduce content that was not present in the source, and that has to be caught before the derivative leaves, not after. Keep unsupported formats or fields in the local validation path and refuse them explicitly; a field that was not inspected is never treated as clean.

Secret detection is separate from personal-data detection. A field that passes one check has not automatically passed the other; a secret finding blocks the run even if the field policy says to remove or redact that field.

Choose what each field keeps

Choose the action that matches the task. These actions are different contracts:

Minimization decides which fields the task needs. Redaction removes a value while leaving a marker, pseudonymization keeps a scoped relationship, and generalization reduces precision. None of these words means anonymous.

Preparation pseudonymizes only fields whose policy action is pseudonymize. A field kept after its checks, such as the issue_text in the example, remains readable in the assigned piece and may still identify someone. The protected local reverse map preserves the relationship for authorized restoration; the alias itself does not make the surrounding text anonymous.

Pseudonymize only identifying values that the task needs to relate across records. Leave useful non-identifying content intact when the policy permits it, and keep the reverse map outside the model context. Proprietary code is not automatically a no-fit, but your declared data policy must permit the release. If your policy requires that no plaintext reach an assigned processing Mac, this workflow is not_fit: preparation can minimize, alias or seal data, but it does not make plaintext unreadable to the Mac that processes its assigned piece.

Keep the decision boundary in place

The three decisions above control only preparation. blocked and review_required keep the copy local until the named condition is resolved; they do not delete the original or release a fallback. eligible permits sealing the prepared copy, but it does not prove anonymity or replace your review of what stayed. Transfer and execution still need their own approval.

Keep the reverse mapping local

When preparation replaces a real identity with a scoped alias, the protected reverse mapping stays in your own environment for the life of the task. It is never included in what leaves your machine. Restoration is item- and field-scoped: it requires a verified result bound to the accepted work, the matching map version, the authorized destination, and the local allowlist. A worker's request or returned alias cannot grant itself restoration.

Pseudonymization is not anonymity. An executing Mac sees the plaintext assigned to its piece while it processes that piece, and a sufficiently privileged or compromised host operator may be able to inspect ordinary process memory. An alias remains linkable within its intended scope. By default, a run-scoped release authority can technically unwrap a block key; it re-wraps that key for the assigned Mac only after the required checks. That is a key-release boundary, not a zero-knowledge guarantee. Managed and customer-held release both follow the approved job or automation policy automatically; no human approves each key grant or eligible retry. Review how your job is split across Macs and encryption and plaintext before choosing a profile for sensitive data.

Production aliases use at least 32 hexadecimal characters, or 128 bits, and 32 hexadecimal characters is the default. The caller supplies key material from its own cryptographically secure random source; the helper checks the production length floor but cannot prove how the key was generated. Keep that key and the protected reverse map in your own environment. Short aliases are available only through the explicit test-only path, which production preparation rejects.

For the agent's selective reading order, see Use the Kit with your agent and the Kit helper reference.

Read data profiles for the categories a profile permits.