/**
 * ApprenticeshipProgram — the standing program scaffold for apprenticeship /
 * mentorship instances (Apprenticeship Step 1, APPRENTICESHIP-STEP1-PROGRAM-
 * SCAFFOLD-SPEC.md).
 *
 * Each instance is a project under a standing program that crystallizes by
 * bootstrap. This module is the instance-as-project REGISTRY plus the two
 * lifecycle GATES that make "review before you start / capture before you
 * close" unskippable at the state-mutating transition:
 *
 *   - the RETRO-GATE (pending→active): refused unless the prior instance's
 *     retro-harvest exists at its CANONICAL CONFINED PATH and passes the
 *     Step 0 validator (the first instance is seeded by the Echo→Codey
 *     bootstrap harvest).
 *   - the DOC-AS-REQUIRED-ARTIFACT GATE (active→complete): refused until the
 *     instance's declared-required artifacts are VERIFIED PRESENT FROM LIVE
 *     STATE (never a stored flag).
 *
 * Signal vs Authority / The Body and the Mind: the gates are structural
 * preconditions on OBJECTIVE artifacts ("does a validated harvest exist?",
 * "is there ≥1 instance-scoped ledger entry?"). They are NOT quality
 * judgments — whether the mentor truly internalized the lessons stays with
 * the overseer (the mind), informed by the gate. Every verdict is appended
 * to logs/apprenticeship-decisions.jsonl (the decision audit).
 *
 * Concurrency: file-backed store at `.instar/apprenticeship/instances.json`,
 * atomic tmp-write+rename, with a single in-process serialized mutator and an
 * optimistic `version` CAS (lost-update safe under the single-process-per-agent
 * AgentServer model). A corrupt/unparseable store FAILS CLOSED — gates return
 * `allow:false`, never "no prior instance → open the gate".
 */
import { type ValidateResult } from './retroHarvestValidator.js';
export type InstanceType = 'apprenticeship' | 'mentorship';
export type InstanceStatus = 'pending' | 'active' | 'complete' | 'blocked';
/** A tracked program-need with its target step + a resolvable honoredBy slot (§4). */
export interface ProgramNeed {
    id: string;
    targetStep: number;
    /**
     * NOT a self-certifying boolean — must reference a concrete, resolvable
     * artifact (a merged spec slug `docs/specs/<slug>.md`, or `pr:<n>`). A
     * later step's gate / review job validates the reference resolves before
     * treating the need as honored. null = still open.
     */
    honoredBy: string | null;
}
export interface ApprenticeshipInstance {
    /** create-time clamp ^[a-z0-9-]+$ ; unique (dup-create rejected). */
    id: string;
    instanceType: InstanceType;
    /** each ^[a-z0-9-]+$ */
    overseer: string;
    mentor: string;
    mentee: string;
    /** ^[a-z0-9-]+$ (flows into the ledger-count query). */
    framework: string;
    status: InstanceStatus;
    /** for the retro-gate; must resolve to a `complete` instance (or null = bootstrap). */
    priorInstanceId: string | null;
    /** the CHECKLIST DEFINITION (what's required), not evidence. Immutable after create. */
    requiredArtifacts: {
        retroHarvest: boolean;
        ledgerEntries: boolean;
        detectorAudit: boolean;
    };
    /** tracked sequencing of the deferred needs (Close-the-Loop). */
    programNeeds: ProgramNeed[];
    /** canonical harvest identity, computed at create (§3.5). harvestFrom = mentor. */
    harvestFrom: string;
    /** harvestTo = mentee. */
    harvestTo: string;
    /** recorded for humans; NEVER the resolution source (§3.5). */
    harvestRef: string | null;
    /** optimistic-CAS counter for the serialized mutator (§3.1). */
    version: number;
    createdAt: string;
    updatedAt: string;
}
export interface CreateInstanceInput {
    id: string;
    instanceType: InstanceType;
    overseer?: string;
    mentor: string;
    mentee: string;
    framework: string;
    priorInstanceId?: string | null;
    requiredArtifacts?: Partial<ApprenticeshipInstance['requiredArtifacts']>;
    programNeeds?: ProgramNeed[];
}
/** Gate verdict shapes (§3.3). */
export interface StartGateVerdict {
    allow: boolean;
    reason: string;
}
export interface CompletionGateVerdict {
    allow: boolean;
    reason: string;
    missing: string[];
}
/**
 * Injected dependencies for the gates (§3.3). Truth is re-derived from these
 * LIVE deps, never from a stored requiredArtifacts boolean. Default impls read
 * the real filesystem / validator; tests inject fakes and wiring-integrity
 * tests assert the real ones are not no-ops.
 */
export interface GateDeps {
    /** Read the canonical harvest text. Returns null when the file is absent. */
    readHarvest: (relPath: string) => string | null;
    /** Validate harvest text (the Step 0 structural validator). */
    validate: (text: string, opts?: {
        priorHarvestExists?: boolean;
    }) => ValidateResult;
    /** Count ledger entries scoped to THIS instance (framework + instance ref). ≥1 required. */
    countInstanceLedgerEntries: (instance: ApprenticeshipInstance) => number;
    /** Does the instance-scoped detector-audit artifact exist? */
    detectorAuditExists: (instance: ApprenticeshipInstance) => boolean;
}
/**
 * Step-4 differential-computation surface (§2). Declared here as a typed no-op
 * interface so its LOCATION is resolved in Step 1; the real implementation
 * lands in Step 4. The overseer (the mind) computes the differential between
 * the mentee's raw streams and the mentor's reports.
 */
export interface ApprenticeshipOverseer {
    /**
     * Compute the differential read-channel for an instance (need-001). The
     * Step-1 stub returns an explicit not-implemented marker — never silently
     * "no differences". Implemented in Step 4.
     */
    computeDifferential(instance: ApprenticeshipInstance): {
        implemented: false;
        reason: string;
    };
}
/** The typed no-op overseer stub (§2). */
export declare const noopApprenticeshipOverseer: ApprenticeshipOverseer;
export interface ApprenticeshipProgramConfig {
    /** Agent state dir (`.instar`). The store lives at `<stateDir>/apprenticeship/instances.json`. */
    stateDir: string;
    /** Project root — the canonical harvest path is resolved against this. */
    projectDir: string;
    /** Decision-audit log path. Default `<stateDir>/logs/apprenticeship-decisions.jsonl`. */
    decisionLogPath?: string;
    /** Override gate deps (tests). Defaults read the real fs + validator. */
    deps?: Partial<GateDeps>;
}
export declare class ApprenticeshipProgram {
    private storePath;
    private decisionLogPath;
    private projectDir;
    private store;
    /** True when the on-disk store was unparseable → gates fail closed. */
    private corrupt;
    private deps;
    constructor(config: ApprenticeshipProgramConfig);
    /** Default harvest reader — resolves the confined relative path under projectDir. */
    private defaultReadHarvest;
    private loadStore;
    private saveStore;
    /**
     * The single in-process serialized mutator with optimistic `version` CAS.
     * JS is single-threaded and `fn` is synchronous, so a straight read → apply
     * → version++ → persist cannot interleave with another mutate() under the
     * single-process model; the CAS guards against a same-tick stale read by
     * re-reading the live record before commit. Returns the persisted snapshot.
     */
    private mutate;
    list(): ApprenticeshipInstance[];
    get(id: string): ApprenticeshipInstance | null;
    /** True when the on-disk store was present but unparseable (gates fail closed). */
    isCorrupt(): boolean;
    /**
     * Create an instance. Charset-clamps id/overseer/mentor/mentee/framework to
     * ^[a-z0-9-]+$, rejects a duplicate id, computes harvestFrom=mentor /
     * harvestTo=mentee. requiredArtifacts defaults to all-required.
     */
    createInstance(input: CreateInstanceInput): ApprenticeshipInstance;
    /**
     * The retro-gate (§3.3). priorInstanceId === null → the bootstrap seed (the
     * Echo→Codey artifact at its canonical path) must exist + validate. Else the
     * prior instance must be status:'complete' AND its canonical harvest must
     * exist + validate. partial-accepted passes ONLY with acceptance metadata
     * (acceptedBy + acceptedAt); complete always passes.
     *
     * The path is recomputed via safeArtifactPath(harvestFrom, harvestTo,
     * instanceType) — never a stored harvestRef.
     */
    evaluateStartGate(instance: ApprenticeshipInstance): StartGateVerdict;
    /**
     * The doc-as-required-artifact gate (§3.3). Each requiredArtifacts flag the
     * instance DECLARES required is checked against LIVE state via injected deps —
     * harvestExists+validates, an instance-scoped ledger count ≥1, detectorAudit
     * present. A stored requiredArtifacts:true is NEVER treated as evidence of
     * presence.
     */
    evaluateCompletionGate(instance: ApprenticeshipInstance): CompletionGateVerdict;
    /**
     * The ONLY way status changes (§3.4). pending→active runs evaluateStartGate
     * and refuses on !allow; active→complete runs evaluateCompletionGate;
     * active→blocked / blocked→active (re-gate) allowed; complete is terminal.
     * Any transition not in the table is rejected with a reason. Every gate
     * verdict is appended to the decision audit.
     */
    transition(id: string, to: InstanceStatus): {
        ok: boolean;
        reason: string;
        instance?: ApprenticeshipInstance;
    };
    private recordDecision;
}
//# sourceMappingURL=ApprenticeshipProgram.d.ts.map