@flyingrobots/graft 0.7.0 → 0.8.0

package/src/contracts/causal-ontology.ts

@@ -1,627 +0,0 @@
-import { z } from "zod";
-
-export const ACTOR_KINDS = [
-  "human",
-  "agent",
-  "git",
-  "daemon",
-  "unknown",
-] as const;
-
-export const actorKindSchema = z.enum(ACTOR_KINDS);
-export type ActorKind = z.infer<typeof actorKindSchema>;
-
-export const AUTHORITY_SCOPES = [
-  "authoritative",
-  "declared",
-  "inferred",
-  "mixed",
-] as const;
-
-export const authorityScopeSchema = z.enum(AUTHORITY_SCOPES);
-export type AuthorityScope = z.infer<typeof authorityScopeSchema>;
-
-export const actorSchema = z.object({
-  actorId: z.string().min(1),
-  actorKind: actorKindSchema,
-  displayName: z.string().min(1).optional(),
-  source: z.string().min(1),
-  authorityScope: authorityScopeSchema,
-}).strict();
-
-export type Actor = z.infer<typeof actorSchema>;
-
-export const EVIDENCE_KINDS = [
-  "mcp_transport_binding",
-  "workspace_authorization",
-  "daemon_session_observation",
-  "explicit_handoff",
-  "git_transition_observation",
-  "git_hook_transition",
-  "git_index_observation",
-  "worktree_fs_observation",
-  "writer_lane_identity",
-  "explicit_user_declaration",
-  "explicit_agent_declaration",
-  "conflicting_actor_signal",
-  "environment_observation",
-  "session_continuity_observation",
-] as const;
-
-export const evidenceKindSchema = z.enum(EVIDENCE_KINDS);
-export type EvidenceKind = z.infer<typeof evidenceKindSchema>;
-
-export const EVIDENCE_STRENGTHS = [
-  "direct",
-  "strong",
-  "weak",
-  "conflicted",
-] as const;
-
-export const evidenceStrengthSchema = z.enum(EVIDENCE_STRENGTHS);
-export type EvidenceStrength = z.infer<typeof evidenceStrengthSchema>;
-
-export const evidenceSchema = z.object({
-  evidenceId: z.string().min(1),
-  evidenceKind: evidenceKindSchema,
-  source: z.string().min(1),
-  capturedAt: z.string().min(1),
-  strength: evidenceStrengthSchema,
-  details: z.record(z.string(), z.unknown()),
-}).strict();
-
-export type Evidence = z.infer<typeof evidenceSchema>;
-
-export const ATTRIBUTION_CONFIDENCES = [
-  "high",
-  "medium",
-  "low",
-  "unknown",
-] as const;
-
-export const attributionConfidenceSchema = z.enum(ATTRIBUTION_CONFIDENCES);
-export type AttributionConfidence = z.infer<typeof attributionConfidenceSchema>;
-
-export const ATTRIBUTION_BASES = [
-  "explicit_declaration",
-  "git_transition",
-  "transport_session",
-  "session_continuity",
-  "environment_inference",
-  "unknown_fallback",
-  "conflicting_signals",
-] as const;
-
-export const attributionBasisSchema = z.enum(ATTRIBUTION_BASES);
-export type AttributionBasis = z.infer<typeof attributionBasisSchema>;
-
-const confidenceRank = Object.freeze({
-  unknown: 0,
-  low: 1,
-  medium: 2,
-  high: 3,
-} as const satisfies Record<AttributionConfidence, number>);
-
-export function getMaximumConfidenceForEvidence(
-  strengths: readonly EvidenceStrength[],
-): AttributionConfidence {
-  if (strengths.length === 0) {
-    return "unknown";
-  }
-  if (strengths.includes("conflicted")) {
-    return "unknown";
-  }
-  if (strengths.includes("direct")) {
-    return "high";
-  }
-  if (strengths.includes("strong")) {
-    return "medium";
-  }
-  if (strengths.includes("weak")) {
-    return "low";
-  }
-  return "unknown";
-}
-
-export function isConfidenceBoundedByEvidence(
-  confidence: AttributionConfidence,
-  strengths: readonly EvidenceStrength[],
-): boolean {
-  return confidenceRank[confidence] <= confidenceRank[getMaximumConfidenceForEvidence(strengths)];
-}
-
-export const attributionSummarySchema = z.object({
-  actor: actorSchema,
-  confidence: attributionConfidenceSchema,
-  basis: attributionBasisSchema,
-  evidence: z.array(evidenceSchema),
-}).strict().superRefine((summary, ctx) => {
-  if (!isConfidenceBoundedByEvidence(
-    summary.confidence,
-    summary.evidence.map((evidence) => evidence.strength),
-  )) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Attribution confidence must be bounded by supporting evidence strength",
-      path: ["confidence"],
-    });
-  }
-});
-
-export type AttributionSummary = z.infer<typeof attributionSummarySchema>;
-
-export const causalRegionSchema = z.object({
-  path: z.string().min(1),
-  startLine: z.number().int().positive(),
-  endLine: z.number().int().positive(),
-  startColumn: z.number().int().positive().optional(),
-  endColumn: z.number().int().positive().optional(),
-}).strict();
-
-export type CausalRegion = z.infer<typeof causalRegionSchema>;
-
-function hasUniqueItems(values: readonly string[]): boolean {
-  return new Set(values).size === values.length;
-}
-
-export const causalFootprintSchema = z.object({
-  paths: z.array(z.string().min(1)),
-  symbols: z.array(z.string().min(1)),
-  regions: z.array(causalRegionSchema),
-}).strict().superRefine((footprint, ctx) => {
-  if (!hasUniqueItems(footprint.paths)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Footprint paths must be unique",
-      path: ["paths"],
-    });
-  }
-  if (!hasUniqueItems(footprint.symbols)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Footprint symbols must be unique",
-      path: ["symbols"],
-    });
-  }
-});
-
-export type CausalFootprint = z.infer<typeof causalFootprintSchema>;
-
-export const SOURCE_LAYERS = [
-  "canonical_structural_truth",
-  "workspace_overlay",
-  "strand_local_speculation",
-] as const;
-
-export const sourceLayerSchema = z.enum(SOURCE_LAYERS);
-export type SourceLayer = z.infer<typeof sourceLayerSchema>;
-
-export const SELECTION_KINDS = [
-  "full_file",
-  "partial_file",
-  "symbol_subset",
-] as const;
-
-export const selectionKindSchema = z.enum(SELECTION_KINDS);
-export type SelectionKind = z.infer<typeof selectionKindSchema>;
-
-export const stagedTargetSelectionEntrySchema = z.object({
-  path: z.string().min(1),
-  symbols: z.array(z.string().min(1)),
-  regions: z.array(causalRegionSchema),
-}).strict().superRefine((entry, ctx) => {
-  if (!hasUniqueItems(entry.symbols)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Selection entry symbols must be unique",
-      path: ["symbols"],
-    });
-  }
-});
-
-export type StagedTargetSelectionEntry = z.infer<typeof stagedTargetSelectionEntrySchema>;
-
-const stagedTargetBaseSchema = z.object({
-  headCommitSha: z.string().min(1),
-  indexTreeSha: z.string().min(1).nullable(),
-}).strict();
-
-export const stagedTargetSchema = z.object({
-  targetId: z.string().min(1),
-  targetKind: z.literal("staged_target"),
-  repoId: z.string().min(1),
-  worktreeId: z.string().min(1),
-  checkoutEpochId: z.string().min(1),
-  workspaceOverlayId: z.string().min(1),
-  selectedAt: z.string().min(1),
-  selectionKind: selectionKindSchema,
-  selectionEntries: z.array(stagedTargetSelectionEntrySchema).min(1),
-  base: stagedTargetBaseSchema,
-}).strict().superRefine((target, ctx) => {
-  const seenPaths = new Set<string>();
-  for (const [index, entry] of target.selectionEntries.entries()) {
-    if (seenPaths.has(entry.path)) {
-      ctx.addIssue({
-        code: "custom",
-        message: "Selection entry paths must be unique within a staged target",
-        path: ["selectionEntries", index, "path"],
-      });
-    }
-    seenPaths.add(entry.path);
-
-    if (target.selectionKind === "full_file" && entry.regions.length > 0) {
-      ctx.addIssue({
-        code: "custom",
-        message: "Full-file staged targets must not carry regions",
-        path: ["selectionEntries", index, "regions"],
-      });
-    }
-    if (target.selectionKind === "partial_file" && entry.regions.length === 0) {
-      ctx.addIssue({
-        code: "custom",
-        message: "Partial-file staged targets require at least one region",
-        path: ["selectionEntries", index, "regions"],
-      });
-    }
-    if (target.selectionKind === "symbol_subset" && entry.symbols.length === 0) {
-      ctx.addIssue({
-        code: "custom",
-        message: "Symbol-subset staged targets require at least one symbol",
-        path: ["selectionEntries", index, "symbols"],
-      });
-    }
-  }
-});
-
-export type StagedTarget = z.infer<typeof stagedTargetSchema>;
-
-export const DECISION_KINDS = [
-  "task_intent",
-  "hypothesis_shift",
-  "accepted_alternative",
-  "rejected_alternative",
-  "checkpoint",
-] as const;
-
-export const decisionKindSchema = z.enum(DECISION_KINDS);
-export type DecisionKind = z.infer<typeof decisionKindSchema>;
-
-export const WRITE_KINDS = [
-  "human_edit",
-  "agent_edit",
-  "git_generated",
-  "stage_projection",
-] as const;
-
-export const writeKindSchema = z.enum(WRITE_KINDS);
-export type WriteKind = z.infer<typeof writeKindSchema>;
-
-export const TRANSITION_KINDS = [
-  "checkout",
-  "merge",
-  "rebase",
-  "reset",
-  "rewrite",
-  "detached_head",
-] as const;
-
-export const transitionKindSchema = z.enum(TRANSITION_KINDS);
-export type TransitionKind = z.infer<typeof transitionKindSchema>;
-
-export const SEMANTIC_TRANSITION_KINDS = [
-  "index_update",
-  "conflict_resolution",
-  "merge_phase",
-  "rebase_phase",
-  "bulk_transition",
-  "unknown",
-] as const;
-
-export const semanticTransitionKindSchema = z.enum(SEMANTIC_TRANSITION_KINDS);
-export type SemanticTransitionKind = z.infer<typeof semanticTransitionKindSchema>;
-
-export const SEMANTIC_TRANSITION_AUTHORITIES = [
-  "authoritative_git_state",
-  "repo_snapshot",
-] as const;
-
-export const semanticTransitionAuthoritySchema = z.enum(SEMANTIC_TRANSITION_AUTHORITIES);
-export type SemanticTransitionAuthority = z.infer<typeof semanticTransitionAuthoritySchema>;
-
-export const REPO_CONCURRENCY_POSTURES = [
-  "exclusive",
-  "shared_repo_only",
-  "shared_worktree",
-  "overlapping_actors",
-  "divergent_checkout",
-  "unknown",
-] as const;
-
-export const repoConcurrencyPostureSchema = z.enum(REPO_CONCURRENCY_POSTURES);
-export type RepoConcurrencyPosture = z.infer<typeof repoConcurrencyPostureSchema>;
-
-export const REPO_CONCURRENCY_AUTHORITIES = [
-  "repo_identity_only",
-  "active_history_scan",
-  "daemon_live_sessions",
-  "footprint_overlap",
-  "explicit_handoff",
-  "unknown",
-] as const;
-
-export const repoConcurrencyAuthoritySchema = z.enum(REPO_CONCURRENCY_AUTHORITIES);
-export type RepoConcurrencyAuthority = z.infer<typeof repoConcurrencyAuthoritySchema>;
-
-export const SEMANTIC_TRANSITION_PHASES = [
-  "started",
-  "conflicted",
-  "resolved_waiting_commit",
-  "continued",
-  "completed_or_cleared",
-] as const;
-
-export const semanticTransitionPhaseSchema = z.enum(SEMANTIC_TRANSITION_PHASES);
-export type SemanticTransitionPhase = z.infer<typeof semanticTransitionPhaseSchema>;
-
-export const HANDOFF_KINDS = [
-  "attach",
-  "resume",
-  "fork",
-  "park",
-] as const;
-
-export const handoffKindSchema = z.enum(HANDOFF_KINDS);
-export type HandoffKind = z.infer<typeof handoffKindSchema>;
-
-export const LOCAL_HISTORY_CONTINUITY_OPERATIONS = [
-  "start",
-  "attach",
-  "resume",
-  "fork",
-  "park",
-] as const;
-
-export const localHistoryContinuityOperationSchema = z.enum(LOCAL_HISTORY_CONTINUITY_OPERATIONS);
-export type LocalHistoryContinuityOperation = z.infer<typeof localHistoryContinuityOperationSchema>;
-
-const causalEventCommonSchema = z.object({
-  eventId: z.string().min(1),
-  repoId: z.string().min(1),
-  worktreeId: z.string().min(1).nullable(),
-  checkoutEpochId: z.string().min(1).nullable(),
-  workspaceOverlayId: z.string().min(1).nullable(),
-  transportSessionId: z.string().min(1).nullable(),
-  workspaceSliceId: z.string().min(1).nullable(),
-  causalSessionId: z.string().min(1).nullable(),
-  strandId: z.string().min(1).nullable(),
-  actorId: z.string().min(1).nullable(),
-  confidence: attributionConfidenceSchema,
-  evidenceIds: z.array(z.string().min(1)),
-  attribution: attributionSummarySchema,
-  footprint: causalFootprintSchema,
-  occurredAt: z.string().min(1),
-}).strict().superRefine((event, ctx) => {
-  if (!hasUniqueItems(event.evidenceIds)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Evidence ids must be unique",
-      path: ["evidenceIds"],
-    });
-  }
-  const attributionEvidenceIds = event.attribution.evidence.map((evidence) => evidence.evidenceId);
-  if (event.actorId !== event.attribution.actor.actorId) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Causal event actorId must match attribution.actor.actorId",
-      path: ["actorId"],
-    });
-  }
-  if (event.confidence !== event.attribution.confidence) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Causal event confidence must match attribution.confidence",
-      path: ["confidence"],
-    });
-  }
-  if (
-    attributionEvidenceIds.length !== event.evidenceIds.length ||
-    attributionEvidenceIds.some((evidenceId, index) => evidenceId !== event.evidenceIds[index])
-  ) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Causal event evidenceIds must match attribution evidence ids in order",
-      path: ["evidenceIds"],
-    });
-  }
-});
-
-const readEventPayloadSchema = z.object({
-  surface: z.string().min(1),
-  projection: z.string().min(1),
-  sourceLayer: sourceLayerSchema,
-  reason: z.string().min(1),
-}).strict();
-
-const writeEventPayloadSchema = z.object({
-  surface: z.string().min(1),
-  writeKind: writeKindSchema,
-  beforeRef: z.string().min(1).optional(),
-  afterRef: z.string().min(1).optional(),
-}).strict();
-
-const decisionEventPayloadSchema = z.object({
-  decisionKind: decisionKindSchema,
-  summary: z.string().min(1),
-}).strict();
-
-const stageEventPayloadSchema = z.object({
-  targetId: z.string().min(1),
-  footprint: causalFootprintSchema,
-  selectionKind: selectionKindSchema,
-}).strict();
-
-const commitEventPayloadSchema = z.object({
-  commitSha: z.string().min(1),
-  parentShas: z.array(z.string().min(1)),
-  message: z.string(),
-}).strict();
-
-const transitionEventPayloadSchema = z.object({
-  semanticKind: semanticTransitionKindSchema,
-  authority: semanticTransitionAuthoritySchema,
-  phase: semanticTransitionPhaseSchema.nullable(),
-  summary: z.string().min(1),
-  transitionKind: transitionKindSchema.nullable(),
-  fromRef: z.string().min(1).nullable(),
-  toRef: z.string().min(1).nullable(),
-  createdCheckoutEpochId: z.string().min(1).nullable(),
-}).strict();
-
-const handoffEventPayloadSchema = z.object({
-  handoffKind: handoffKindSchema,
-  fromActorId: z.string().min(1).optional(),
-  toActorId: z.string().min(1).optional(),
-  notes: z.string().min(1).optional(),
-}).strict();
-
-export const readEventSchema = causalEventCommonSchema.extend({
-  eventKind: z.literal("read"),
-  payload: readEventPayloadSchema,
-}).strict();
-
-export const writeEventSchema = causalEventCommonSchema.extend({
-  eventKind: z.literal("write"),
-  payload: writeEventPayloadSchema,
-}).strict();
-
-export const decisionEventSchema = causalEventCommonSchema.extend({
-  eventKind: z.literal("decision"),
-  payload: decisionEventPayloadSchema,
-}).strict();
-
-export const stageEventSchema = causalEventCommonSchema.extend({
-  eventKind: z.literal("stage"),
-  payload: stageEventPayloadSchema,
-}).strict();
-
-export const commitEventSchema = causalEventCommonSchema.extend({
-  eventKind: z.literal("commit"),
-  payload: commitEventPayloadSchema,
-}).strict();
-
-export const transitionEventSchema = causalEventCommonSchema.extend({
-  eventKind: z.literal("transition"),
-  payload: transitionEventPayloadSchema,
-}).strict();
-
-export const handoffEventSchema = causalEventCommonSchema.extend({
-  eventKind: z.literal("handoff"),
-  payload: handoffEventPayloadSchema,
-}).strict();
-
-export const causalEventSchema = z.discriminatedUnion("eventKind", [
-  readEventSchema,
-  writeEventSchema,
-  decisionEventSchema,
-  stageEventSchema,
-  commitEventSchema,
-  transitionEventSchema,
-  handoffEventSchema,
-]);
-
-export type CausalEvent = z.infer<typeof causalEventSchema>;
-
-export const CAUSAL_PERSISTENCE_CLASSES = [
-  "canonical_structural_truth",
-  "canonical_provenance",
-  "strand_local",
-  "discardable",
-] as const;
-
-export const causalPersistenceClassSchema = z.enum(CAUSAL_PERSISTENCE_CLASSES);
-export type CausalPersistenceClass = z.infer<typeof causalPersistenceClassSchema>;
-
-export const COLLAPSE_TARGET_KINDS = [
-  "staged_target",
-  "commit",
-] as const;
-
-export const collapseTargetKindSchema = z.enum(COLLAPSE_TARGET_KINDS);
-export type CollapseTargetKind = z.infer<typeof collapseTargetKindSchema>;
-
-export const EXCLUSION_REASONS = [
-  "outside_target_footprint",
-  "different_checkout_epoch",
-  "different_causal_session",
-  "insufficient_evidence",
-  "precedes_selection_boundary",
-] as const;
-
-export const exclusionReasonSchema = z.enum(EXCLUSION_REASONS);
-export type ExclusionReason = z.infer<typeof exclusionReasonSchema>;
-
-const collapseBoundarySchema = z.object({
-  afterEventId: z.string().min(1),
-  reason: exclusionReasonSchema,
-  note: z.string().min(1).optional(),
-}).strict();
-
-export const collapseWitnessSchema = z.object({
-  collapseRecordId: z.string().min(1),
-  targetKind: collapseTargetKindSchema,
-  targetId: z.string().min(1),
-  targetFootprint: causalFootprintSchema,
-  base: z.object({
-    repoId: z.string().min(1),
-    checkoutEpochId: z.string().min(1),
-    commitSha: z.string().min(1),
-  }).strict(),
-  causalSessionId: z.string().min(1),
-  strandIds: z.array(z.string().min(1)).min(1),
-  includedEventIds: z.array(z.string().min(1)).min(1),
-  sharedEventIds: z.array(z.string().min(1)),
-  excludedBoundaries: z.array(collapseBoundarySchema),
-  evidenceIds: z.array(z.string().min(1)).min(1),
-  confidence: attributionConfidenceSchema,
-  createdAt: z.string().min(1),
-}).strict().superRefine((witness, ctx) => {
-  if (!hasUniqueItems(witness.strandIds)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Strand ids must be unique",
-      path: ["strandIds"],
-    });
-  }
-  if (!hasUniqueItems(witness.includedEventIds)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Included event ids must be unique",
-      path: ["includedEventIds"],
-    });
-  }
-  if (!hasUniqueItems(witness.sharedEventIds)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Shared event ids must be unique",
-      path: ["sharedEventIds"],
-    });
-  }
-  for (const [index, sharedEventId] of witness.sharedEventIds.entries()) {
-    if (!witness.includedEventIds.includes(sharedEventId)) {
-      ctx.addIssue({
-        code: "custom",
-        message: "Shared events must also appear in includedEventIds",
-        path: ["sharedEventIds", index],
-      });
-    }
-  }
-  if (!hasUniqueItems(witness.evidenceIds)) {
-    ctx.addIssue({
-      code: "custom",
-      message: "Witness evidence ids must be unique",
-      path: ["evidenceIds"],
-    });
-  }
-});
-
-export type CollapseWitness = z.infer<typeof collapseWitnessSchema>;

package/src/contracts/causal-surface-next-action.ts

@@ -1,18 +0,0 @@
-import { z } from "zod";
-
-export const CAUSAL_SURFACE_NEXT_ACTIONS = [
-  "bind_workspace_to_begin_local_history",
-  "continue_active_causal_workspace",
-  "review_transition_boundary_before_continuing",
-  "inspect_or_resume_local_history",
-  "coordinate_shared_worktree_before_continuing",
-  "inspect_overlapping_actor_activity_before_continuing",
-  "review_divergent_checkout_before_continuing",
-  "resolve_conflicts_before_continuing",
-  "complete_merge_phase_before_continuing",
-  "continue_rebase_phase_before_continuing",
-  "inspect_bulk_transition_scope_before_continuing",
-] as const;
-
-export const causalSurfaceNextActionSchema = z.enum(CAUSAL_SURFACE_NEXT_ACTIONS);
-export type CausalSurfaceNextAction = z.infer<typeof causalSurfaceNextActionSchema>;

package/src/contracts/json-object.ts

@@ -1,18 +0,0 @@
-import { z } from "zod";
-
-export const jsonObjectSchema = z.object({}).catchall(z.unknown());
-
-export type JsonObject = z.infer<typeof jsonObjectSchema>;
-
-export function parseJsonObject(value: unknown, label: string): JsonObject {
-  const parsed = jsonObjectSchema.safeParse(value);
-  if (!parsed.success) {
-    throw new Error(`${label} was not a JSON object`);
-  }
-  return parsed.data;
-}
-
-export function tryParseJsonObject(value: unknown): JsonObject | null {
-  const parsed = jsonObjectSchema.safeParse(value);
-  return parsed.success ? parsed.data : null;
-}

package/src/contracts/mcp-runtime.ts

@@ -1,16 +0,0 @@
-export const MCP_RUNTIME_MODES = ["repo-local", "daemon"] as const;
-
-export type McpRuntimeMode = typeof MCP_RUNTIME_MODES[number];
-
-export function parseMcpRuntimeMode(
-  raw: string | undefined,
-  flag: string,
-): McpRuntimeMode {
-  if (raw === undefined) {
-    return "repo-local";
-  }
-  if (raw === "repo-local" || raw === "daemon") {
-    return raw;
-  }
-  throw new Error(`${flag} must be one of: ${MCP_RUNTIME_MODES.join(", ")}`);
-}