@asc-agent/runtime 0.1.0

package/dist/core/runtime/audit.d.ts

@@ -0,0 +1,374 @@
+import { z } from 'zod';
+import type { ScopedStore } from '../../ports/state-store.ts';
+/**
+ * principal 신고 수준 (C-10 §3).
+ *
+ * ASC는 신고를 검증할 수단이 없다. Host attestation이 없는 상태에서 "검증했다"고 쓰는 것이
+ * 검증하지 않는 것보다 나쁘므로, 검증 대신 **신고 수준을 기록**한다.
+ */
+export declare const PrincipalSource: z.ZodEnum<["declared", "derived"]>;
+export type PrincipalSource = z.infer<typeof PrincipalSource>;
+export declare const ExecutionStatus: z.ZodEnum<["RUNNING", "RELEASED", "SUPERSEDED"]>;
+export type ExecutionStatus = z.infer<typeof ExecutionStatus>;
+export declare const DelegationRecord: z.ZodObject<{
+    delegationId: z.ZodString;
+    /** 위임한 세션. 없으면 최상위 발급이다 — 없는 부모를 지어내지 않는다. */
+    parentSessionId: z.ZodOptional<z.ZodString>;
+    childSessionId: z.ZodString;
+    role: z.ZodString;
+    goal: z.ZodString;
+    /** 세션 계약의 사본이 아니라 발급 시점 요약. 정본은 Session entity다. */
+    scope: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    doneCriteria: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    issuedBy: z.ZodString;
+    issuedAt: z.ZodString;
+    /** 결과를 누구에게 돌려야 하는가. 보통 parentSessionId. */
+    expectedReturnTo: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: string;
+    goal: string;
+    doneCriteria: string[];
+    issuedBy: string;
+    issuedAt: string;
+    scope: string[];
+    delegationId: string;
+    childSessionId: string;
+    parentSessionId?: string | undefined;
+    expectedReturnTo?: string | undefined;
+}, {
+    role: string;
+    goal: string;
+    issuedBy: string;
+    issuedAt: string;
+    delegationId: string;
+    childSessionId: string;
+    doneCriteria?: string[] | undefined;
+    scope?: string[] | undefined;
+    parentSessionId?: string | undefined;
+    expectedReturnTo?: string | undefined;
+}>;
+export type DelegationRecord = z.infer<typeof DelegationRecord>;
+export declare const ExecutionEvidence: z.ZodObject<{
+    executionId: z.ZodString;
+    logicalSessionId: z.ZodString;
+    /** 어느 Host가 관찰했는가. provider 이름이 아니라 adapter id다. */
+    hostAdapter: z.ZodString;
+    principal: z.ZodString;
+    principalSource: z.ZodEnum<["declared", "derived"]>;
+    /** Host가 아는 실행 참조(physical session id 등). 같은 사람이 여럿 가질 수 있다. */
+    physicalReference: z.ZodString;
+    startedAt: z.ZodString;
+    finishedAt: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<["RUNNING", "RELEASED", "SUPERSEDED"]>;
+    /** 이 사실이 어디서 왔는가 — 선언인가 관찰인가. */
+    evidenceSource: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: "RUNNING" | "RELEASED" | "SUPERSEDED";
+    logicalSessionId: string;
+    executionId: string;
+    hostAdapter: string;
+    principal: string;
+    principalSource: "declared" | "derived";
+    physicalReference: string;
+    startedAt: string;
+    evidenceSource: string;
+    finishedAt?: string | undefined;
+}, {
+    status: "RUNNING" | "RELEASED" | "SUPERSEDED";
+    logicalSessionId: string;
+    executionId: string;
+    hostAdapter: string;
+    principal: string;
+    principalSource: "declared" | "derived";
+    physicalReference: string;
+    startedAt: string;
+    evidenceSource: string;
+    finishedAt?: string | undefined;
+}>;
+export type ExecutionEvidence = z.infer<typeof ExecutionEvidence>;
+declare const ExecutionEnd: z.ZodObject<{
+    finishedAt: z.ZodString;
+    status: z.ZodEnum<["RELEASED", "SUPERSEDED"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "RELEASED" | "SUPERSEDED";
+    finishedAt: string;
+}, {
+    status: "RELEASED" | "SUPERSEDED";
+    finishedAt: string;
+}>;
+type ExecutionEnd = z.infer<typeof ExecutionEnd>;
+export declare const ReclaimEvidence: z.ZodObject<{
+    sessionId: z.ZodString;
+    /** 회수 주체. 모르면 기록하지 않는다 — 익명 회수는 감사 공백이다 (C-10 §2.4 불변식 ⑥). */
+    reclaimedBy: z.ZodString;
+    reclaimedAt: z.ZodString;
+    /** 무엇을 받았는가. Handoff 시각으로 가리킨다 — 본문을 복제하지 않는다. */
+    handoffRef: z.ZodOptional<z.ZodString>;
+    /** 회수 시점에 살아 있던 실행들. archive 뒤에는 세션에서 복원되지 않는다. */
+    executionRefs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    reclaimedBy: string;
+    reclaimedAt: string;
+    executionRefs: string[];
+    handoffRef?: string | undefined;
+}, {
+    sessionId: string;
+    reclaimedBy: string;
+    reclaimedAt: string;
+    handoffRef?: string | undefined;
+    executionRefs?: string[] | undefined;
+}>;
+export type ReclaimEvidence = z.infer<typeof ReclaimEvidence>;
+/**
+ * 독립성 등급 (C-10 §4.2).
+ *
+ * ASC는 principal 신고를 검증하지 못한다. 그래서 "다르다"고 말할 수 있는 조건을
+ * 좁게 잡는다 — 양쪽 모두 선언됐고 실제로 다를 때만 독립이다.
+ */
+export declare const Independence: z.ZodEnum<["INDEPENDENT", "SELF_REPORTED", "UNVERIFIED"]>;
+export type Independence = z.infer<typeof Independence>;
+export declare const ValidationRecord: z.ZodObject<{
+    validationId: z.ZodString;
+    validatorSessionId: z.ZodString;
+    /** 그 검증을 실제로 수행한 실행. 없으면 검증 세션이 있다는 주장뿐이다. */
+    validatorExecutionId: z.ZodString;
+    principal: z.ZodString;
+    principalSource: z.ZodEnum<["declared", "derived"]>;
+    targetSessionId: z.ZodString;
+    /** 무엇을 보고 판정했는가. Handoff 시각·리비전으로 가리킨다. */
+    targetHandoffRef: z.ZodOptional<z.ZodString>;
+    targetRevision: z.ZodOptional<z.ZodString>;
+    result: z.ZodEnum<["PASS", "FAIL"]>;
+    /** 무엇을 봤는가. 결과만 남기면 다음 사람이 다시 볼 수 없다. */
+    findings: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    verifiedAt: z.ZodString;
+    independence: z.ZodEnum<["INDEPENDENT", "SELF_REPORTED", "UNVERIFIED"]>;
+    /** 왜 그 등급인가. 등급만 있으면 뒤집을 근거가 없다. */
+    independenceDetail: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    findings: string[];
+    result: "PASS" | "FAIL";
+    principal: string;
+    principalSource: "declared" | "derived";
+    validationId: string;
+    validatorSessionId: string;
+    validatorExecutionId: string;
+    targetSessionId: string;
+    verifiedAt: string;
+    independence: "INDEPENDENT" | "SELF_REPORTED" | "UNVERIFIED";
+    independenceDetail: string;
+    targetHandoffRef?: string | undefined;
+    targetRevision?: string | undefined;
+}, {
+    result: "PASS" | "FAIL";
+    principal: string;
+    principalSource: "declared" | "derived";
+    validationId: string;
+    validatorSessionId: string;
+    validatorExecutionId: string;
+    targetSessionId: string;
+    verifiedAt: string;
+    independence: "INDEPENDENT" | "SELF_REPORTED" | "UNVERIFIED";
+    independenceDetail: string;
+    findings?: string[] | undefined;
+    targetHandoffRef?: string | undefined;
+    targetRevision?: string | undefined;
+}>;
+export type ValidationRecord = z.infer<typeof ValidationRecord>;
+/**
+ * 승인 없이 내린 결정의 갈래 (C-13 §4.1).
+ *
+ * 앞 넷은 자율 판단의 자리이고, 뒤 다섯은 escalation predicate와 짝을 이룬다 —
+ * 뒤쪽 class로 결정을 내렸는데 상신이 없으면 그 자체가 이상 신호다.
+ */
+export declare const DecisionClass: z.ZodEnum<["implementation_detail", "owned_contract_consumption", "local_test_strategy", "local_refactor", "external_boundary", "shared_contract", "acceptance", "permission", "irreversible"]>;
+export type DecisionClass = z.infer<typeof DecisionClass>;
+/**
+ * 승인 없이 갔다는 것이 기록이 없어도 된다는 뜻은 아니다 (C-13 §4).
+ *
+ * **부여받은 authority 안에서의 자율 판단임을 감사 가능하게** 남긴다. 무엇과 견줬는지
+ * (alternatives)가 없으면 비교 없이 고른 것과 구분되지 않는다.
+ */
+export declare const DecisionEvidence: z.ZodObject<{
+    decisionId: z.ZodString;
+    sessionId: z.ZodString;
+    actor: z.ZodString;
+    /** 어느 권한 안에서 내렸는가. 비어 있으면 권한을 대지 못한 결정이다. */
+    ownership: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    class: z.ZodEnum<["implementation_detail", "owned_contract_consumption", "local_test_strategy", "local_refactor", "external_boundary", "shared_contract", "acceptance", "permission", "irreversible"]>;
+    evidenceRefs: z.ZodArray<z.ZodString, "atleastone">;
+    selectedOption: z.ZodString;
+    alternatives: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** 왜 경계가 아니었는가. 이것이 없으면 자율 판단이 아니라 그냥 안 물어본 것이다. */
+    whyNoApproval: z.ZodArray<z.ZodString, "atleastone">;
+    verification: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    decidedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    evidenceRefs: [string, ...string[]];
+    actor: string;
+    decidedAt: string;
+    sessionId: string;
+    verification: string[];
+    ownership: string[];
+    decisionId: string;
+    class: "implementation_detail" | "owned_contract_consumption" | "local_test_strategy" | "local_refactor" | "external_boundary" | "shared_contract" | "acceptance" | "permission" | "irreversible";
+    selectedOption: string;
+    alternatives: string[];
+    whyNoApproval: [string, ...string[]];
+}, {
+    evidenceRefs: [string, ...string[]];
+    actor: string;
+    decidedAt: string;
+    sessionId: string;
+    decisionId: string;
+    class: "implementation_detail" | "owned_contract_consumption" | "local_test_strategy" | "local_refactor" | "external_boundary" | "shared_contract" | "acceptance" | "permission" | "irreversible";
+    selectedOption: string;
+    whyNoApproval: [string, ...string[]];
+    verification?: string[] | undefined;
+    ownership?: string[] | undefined;
+    alternatives?: string[] | undefined;
+}>;
+export type DecisionEvidence = z.infer<typeof DecisionEvidence>;
+export type DecisionOutcome = {
+    ok: true;
+    decision: DecisionEvidence;
+};
+export type DelegationOutcome = {
+    ok: true;
+    record: DelegationRecord;
+} | {
+    ok: false;
+    reason: 'ALREADY_RECORDED';
+    detail: string;
+    existing: DelegationRecord;
+};
+export type ExecutionOutcome = {
+    ok: true;
+    evidence: ExecutionEvidence;
+};
+export type EndOutcome = {
+    ok: true;
+    evidence: ExecutionEvidence;
+} | {
+    ok: false;
+    reason: 'NOT_FOUND' | 'ALREADY_ENDED';
+    detail: string;
+};
+export type ValidationOutcome = {
+    ok: true;
+    record: ValidationRecord;
+} | {
+    ok: false;
+    reason: 'NO_VALIDATOR_EXECUTION';
+    detail: string;
+} | {
+    ok: false;
+    reason: 'ALREADY_RECORDED';
+    detail: string;
+};
+export type ReclaimOutcome = {
+    ok: true;
+    record: ReclaimEvidence;
+} | {
+    ok: false;
+    reason: 'ALREADY_RECLAIMED';
+    detail: string;
+};
+export declare class AuditLedger {
+    #private;
+    constructor(scope: ScopedStore, now?: () => string);
+    /**
+     * 위임을 선언으로 기록한다.
+     *
+     * **상태 전이를 일으키지 않는다** (C-10 §1.2 불변식 ②). 전이는 전이표만 한다.
+     * 두 번째 위임 선언은 조용히 덮지 않고 거부한다 — 같은 세션을 두 번 맡겼다면
+     * 그건 기록이 아니라 사고이므로 사람이 봐야 한다.
+     */
+    delegate(input: Omit<DelegationRecord, 'delegationId' | 'issuedAt'> & {
+        issuedAt?: string;
+    }): Promise<DelegationOutcome>;
+    delegationOf(childSessionId: string): Promise<DelegationRecord | null>;
+    /** 이 세션이 위임한 것들. parent 축으로 본다. */
+    delegationsFrom(parentSessionId: string): Promise<DelegationRecord[]>;
+    /**
+     * 실행이 실제로 시작됐다는 사실을 남긴다.
+     *
+     * 순번은 setIfAbsent가 성공할 때까지 올린다 — 읽고-고쳐-쓰기를 하면 두 실행이 동시에
+     * 붙을 때 하나가 조용히 사라진다. 실패는 경쟁이지 오류가 아니므로 다음 번호로 간다.
+     */
+    execute(input: Omit<ExecutionEvidence, 'executionId' | 'status' | 'finishedAt' | 'startedAt'> & {
+        startedAt?: string;
+    }): Promise<ExecutionOutcome>;
+    /**
+     * 실행이 끝났다. **시작 기록을 고치지 않고 끝 마커를 따로 남긴다** —
+     * 현재 소유권(Runtime Binding)은 사라져도 "그때 그 실행이 있었다"는 사실은 남아야 한다
+     * (C-10 §1.3 불변식 ④).
+     */
+    endExecution(executionId: string, status: ExecutionEnd['status'], at?: string): Promise<EndOutcome>;
+    /** 이 세션을 거쳐 간 실행 전부. 순서는 순번 순 — 회수 후에도 남는다. */
+    executionsOf(logicalSessionId: string): Promise<ExecutionEvidence[]>;
+    /**
+     * Controller가 실제로 회수했다는 별도 증거.
+     *
+     * 회수 시점에 살아 있던 실행을 함께 붙인다 — archive 이후에는 세션에서 그것을
+     * 되찾을 수 없기 때문이다 (C-10 §2.4).
+     */
+    reclaim(input: Omit<ReclaimEvidence, 'executionRefs'>): Promise<ReclaimOutcome>;
+    reclaimOf(sessionId: string): Promise<ReclaimEvidence | null>;
+    /**
+     * 검증 결과를 기록한다.
+     *
+     * **검증자의 실행 증거가 없으면 기록하지 않는다** (C-10 §4). 세션 id만 만들어 두고
+     * "검증했다"고 적는 것이 정확히 이 계약이 막는 것이다.
+     *
+     * 독립성은 주장이 아니라 판정이다 — 여기서 계산해 넣고, 호출자가 정하지 못한다.
+     */
+    validate(input: {
+        validatorSessionId: string;
+        targetSessionId: string;
+        result: 'PASS' | 'FAIL';
+        findings?: readonly string[];
+        targetHandoffRef?: string;
+        targetRevision?: string;
+        verifiedAt?: string;
+    }): Promise<ValidationOutcome>;
+    /** 이 세션에 대한 검증들. 없으면 빈 배열 — "검증 없음"도 사실이다. */
+    validationsOf(targetSessionId: string): Promise<ValidationRecord[]>;
+    /**
+     * 승인 없이 내린 결정을 남긴다.
+     *
+     * 순번은 setIfAbsent가 성공할 때까지 올린다 — 같은 세션의 두 결정이 겹쳐도 하나가
+     * 조용히 사라지지 않는다 (execute와 같은 형태).
+     */
+    decide(input: Omit<DecisionEvidence, 'decisionId' | 'decidedAt'> & {
+        decidedAt?: string;
+    }): Promise<DecisionOutcome>;
+    /** 이 세션이 스스로 정한 것들. 승인 기록과 나란히 놓고 보는 것이 목적이다. */
+    decisionsOf(sessionId: string): Promise<DecisionEvidence[]>;
+}
+/**
+ * 사람이 읽는 줄. **없는 단계를 비워 두지 않고 없다고 적는다** (C-10 §5 불변식 ⑩).
+ * "실행 증거 없음"은 감춰야 할 결함이 아니라 정상 출력이다.
+ */
+export declare function executionLines(evidence: readonly ExecutionEvidence[]): string[];
+/**
+ * 검증자와 피검증자가 실제로 다른 주체인가 (C-10 §4.2).
+ *
+ * 대상 쪽 실행이 하나도 없으면 비교할 상대가 없다 — 그것도 UNVERIFIED다.
+ * "다른 실행이 없으니 독립이다"는 가장 위험한 오판이다.
+ */
+export declare function judgeIndependence(validator: ExecutionEvidence, targetRuns: readonly ExecutionEvidence[]): {
+    independence: Independence;
+    detail: string;
+};
+/** 사람이 읽는 검증 줄. **등급만 적고 이유를 빼지 않는다.** */
+export declare function validationLines(records: readonly ValidationRecord[]): string[];
+/**
+ * 사람이 읽는 결정 줄. **왜 승인이 필요 없었는지가 함께 온다** — 그 이유가 빠지면
+ * "그냥 안 물어봤다"와 구분되지 않는다.
+ */
+export declare function decisionLines(decisions: readonly DecisionEvidence[]): string[];
+export declare function reclaimLine(record: ReclaimEvidence | null, sessionId: string): string;
+export declare function delegationLine(record: DelegationRecord | null, childSessionId: string): string;
+export {};