syncpoint-ai 0.1.0

package/dist/kernel/relationship-mode.js

@@ -0,0 +1,204 @@
+/**
+ * Relationship Mode — explicit coordination patterns between agents.
+ *
+ * Three modes, each with distinct synchronization rules:
+ *
+ *   manager-delegate:  delegate → wait → report → review
+ *   peer-contract:     contract → parallel work → checkpoint sync → merge
+ *   handoff-resume:    snapshot → handoff → accept → resume
+ *
+ * Housed in kernel because both syncpoint-adapters (playbook engine) and
+ * syncpoint-governance (wake engine) depend on these types at runtime.
+ */
+import { z } from "zod";
+// ── Mode ────────────────────────────────────────────
+export var RelationshipMode;
+(function (RelationshipMode) {
+    RelationshipMode["MANAGER_DELEGATE"] = "manager-delegate";
+    RelationshipMode["PEER_CONTRACT"] = "peer-contract";
+    RelationshipMode["HANDOFF_RESUME"] = "handoff-resume";
+})(RelationshipMode || (RelationshipMode = {}));
+export const RelationshipModeSchema = z.nativeEnum(RelationshipMode);
+// ── Phase flow per mode ─────────────────────────────
+/**
+ * The expected phase sequence for each mode.
+ * These are the "sync verbs" that wake/playbook should enforce.
+ */
+export const MODE_PHASE_FLOW = {
+    [RelationshipMode.MANAGER_DELEGATE]: [
+        "plan", // architect plans & delegates
+        "accept", // executor accepts assignment
+        "work", // executor works (with checkpoints)
+        "checkpoint", // executor creates checkpoint
+        "report", // executor completes → reports back
+        "review", // reviewer/architect reviews
+        "approve", // reviewer approves or requests changes
+    ],
+    [RelationshipMode.PEER_CONTRACT]: [
+        "contract", // peers agree on scope boundary
+        "claim-resources", // each peer claims resource ownership
+        "work", // parallel work (with checkpoints)
+        "checkpoint", // checkpoint to sync state
+        "sync", // sync gate when overlap detected
+        "merge", // merge results after sync
+        "review", // mutual or third-party review
+    ],
+    [RelationshipMode.HANDOFF_RESUME]: [
+        "snapshot", // current agent creates context snapshot
+        "handoff", // handoff to next agent
+        "accept", // next agent accepts handoff
+        "resume", // next agent resumes with snapshot context
+        "work", // next agent works
+        "checkpoint", // checkpoint progress
+    ],
+};
+export const MODE_SYNC_RULES = {
+    [RelationshipMode.MANAGER_DELEGATE]: {
+        requiresSyncGate: false,
+        requiresResourceClaim: false,
+        requiresCheckpoint: true,
+        requiresReview: true,
+        allowsParallelWork: false,
+    },
+    [RelationshipMode.PEER_CONTRACT]: {
+        requiresSyncGate: true,
+        requiresResourceClaim: true,
+        requiresCheckpoint: true,
+        requiresReview: true,
+        allowsParallelWork: true,
+    },
+    [RelationshipMode.HANDOFF_RESUME]: {
+        requiresSyncGate: false,
+        requiresResourceClaim: false,
+        requiresCheckpoint: true,
+        requiresReview: false,
+        allowsParallelWork: false,
+    },
+};
+// ── Wake verb whitelist per mode ────────────────────
+/**
+ * Which wake actions are valid for each mode.
+ * This is used by P4 to restrict wake generation.
+ */
+export const MODE_WAKE_VERBS = {
+    [RelationshipMode.MANAGER_DELEGATE]: [
+        "plan", "plan-tasks", "accept", "accept-assignment",
+        "checkpoint", "review", "start-review", "request-review",
+        "approve", "advance-session", "resume", "address-changes",
+    ],
+    [RelationshipMode.PEER_CONTRACT]: [
+        "plan", "plan-tasks", "accept", "accept-assignment",
+        "claim-resources", "checkpoint", "sync", "sync-checkpoint",
+        "review", "start-review", "request-review",
+        "approve", "advance-session", "resume", "address-changes",
+    ],
+    [RelationshipMode.HANDOFF_RESUME]: [
+        "snapshot", "handoff", "accept", "accept-assignment",
+        "resume", "checkpoint", "plan", "plan-tasks",
+        "advance-session",
+    ],
+};
+/**
+ * Actions that MUST be performed before an agent can start work in this mode.
+ */
+export const REQUIRED_BEFORE_START = {
+    [RelationshipMode.MANAGER_DELEGATE]: [
+        "accept",
+    ],
+    [RelationshipMode.PEER_CONTRACT]: [
+        "accept",
+        "claim-resources",
+    ],
+    [RelationshipMode.HANDOFF_RESUME]: [
+        "accept",
+    ],
+};
+/**
+ * Actions that are recommended (but not required) in each mode.
+ */
+export const RECOMMENDED_ACTIONS = {
+    [RelationshipMode.MANAGER_DELEGATE]: [
+        "checkpoint", "review", "approve",
+    ],
+    [RelationshipMode.PEER_CONTRACT]: [
+        "checkpoint", "sync-checkpoint", "review",
+    ],
+    [RelationshipMode.HANDOFF_RESUME]: [
+        "checkpoint", "snapshot", "handoff",
+    ],
+};
+/**
+ * Actions that should NEVER be generated for this mode (in wake/playbook).
+ */
+export const FORBIDDEN_ACTIONS = {
+    [RelationshipMode.MANAGER_DELEGATE]: [
+        "claim-resources", "sync-checkpoint", "handoff", "snapshot",
+    ],
+    [RelationshipMode.PEER_CONTRACT]: [
+        "handoff", "snapshot",
+    ],
+    [RelationshipMode.HANDOFF_RESUME]: [
+        "claim-resources", "sync-checkpoint", "start-review", "request-review",
+    ],
+};
+// ── Pure helpers ────────────────────────────────────
+/**
+ * Check if a wake action verb is valid for a given mode.
+ */
+export function isValidWakeVerb(mode, action) {
+    return MODE_WAKE_VERBS[mode]?.includes(action) ?? false;
+}
+/**
+ * Get the sync rules for a given mode.
+ */
+export function getSyncRules(mode) {
+    return MODE_SYNC_RULES[mode];
+}
+/**
+ * Get the expected phase flow for a given mode.
+ */
+export function getPhaseFlow(mode) {
+    return MODE_PHASE_FLOW[mode];
+}
+/**
+ * Get a human-readable description of a mode's coordination pattern.
+ */
+export function getModeDescription(mode) {
+    switch (mode) {
+        case RelationshipMode.MANAGER_DELEGATE:
+            return "Manager delegates tasks to executor(s). Executor reports back. Manager/reviewer approves. Sequential, hierarchical coordination.";
+        case RelationshipMode.PEER_CONTRACT:
+            return "Peers agree on scope boundaries via contracts. Resource claims prevent conflicts. Sync gates enforce coordination at overlap points. Parallel work with structured merge.";
+        case RelationshipMode.HANDOFF_RESUME:
+            return "One agent packages context into a snapshot and hands off to the next. Sequential relay — each agent picks up where the previous left off.";
+    }
+}
+/**
+ * Determine if a given action is allowed, recommended, or blocked for a mode.
+ */
+export function isModeActionAllowed(mode, action) {
+    if (FORBIDDEN_ACTIONS[mode].includes(action))
+        return "blocked";
+    if (RECOMMENDED_ACTIONS[mode].includes(action))
+        return "recommended";
+    return "allowed";
+}
+/**
+ * Get actions required before an agent can start work in this mode.
+ */
+export function getRequiredBeforeStart(mode) {
+    return REQUIRED_BEFORE_START[mode];
+}
+/**
+ * Get recommended actions for a mode.
+ */
+export function getRecommendedActions(mode) {
+    return RECOMMENDED_ACTIONS[mode];
+}
+/**
+ * Get forbidden actions for a mode.
+ */
+export function getForbiddenActions(mode) {
+    return FORBIDDEN_ACTIONS[mode];
+}
+//# sourceMappingURL=relationship-mode.js.map

package/dist/kernel/relationship-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-mode.js","sourceRoot":"","sources":["../../_build/src/kernel/relationship-mode.ts"],"names":[],"mappings":"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"}

package/dist/kernel/resource.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Resource — generic resource reference and claim protocol.
+ *
+ * Provides pluggable locator overlap detection via ResourceMatcher.
+ * Plugins register matchers for specific resource types (e.g. "file");
+ * unknown types fall back to exact locator equality.
+ */
+import { z } from "zod";
+/**
+ * A reference to any addressable resource in the project.
+ */
+export declare const ResourceScope: z.ZodEnum<["file", "function", "line_range"]>;
+export type ResourceScope = z.infer<typeof ResourceScope>;
+export declare const LineRangeSchema: z.ZodObject<{
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    start: number;
+    end: number;
+}, {
+    start: number;
+    end: number;
+}>;
+export type LineRange = z.infer<typeof LineRangeSchema>;
+export declare const ResourceRefSchema: z.ZodObject<{
+    type: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+    locator: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<["file", "function", "line_range"]>>;
+    functionName: z.ZodOptional<z.ZodString>;
+    lineRange: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        start: number;
+        end: number;
+    }, {
+        start: number;
+        end: number;
+    }>>;
+    metadata: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    locator: string;
+    scope: "function" | "file" | "line_range";
+    metadata: string;
+    id?: string | undefined;
+    functionName?: string | undefined;
+    lineRange?: {
+        start: number;
+        end: number;
+    } | undefined;
+}, {
+    type: string;
+    locator: string;
+    id?: string | undefined;
+    scope?: "function" | "file" | "line_range" | undefined;
+    functionName?: string | undefined;
+    lineRange?: {
+        start: number;
+        end: number;
+    } | undefined;
+    metadata?: string | undefined;
+}>;
+export type ResourceRef = z.infer<typeof ResourceRefSchema>;
+export declare enum ResourceClaimStatus {
+    ACTIVE = "ACTIVE",
+    RELEASED = "RELEASED"
+}
+export declare enum ResourceClaimMode {
+    EXCLUSIVE = "exclusive",
+    SHARED = "shared"
+}
+export declare const ResourceClaimSchema: z.ZodObject<{
+    id: z.ZodString;
+    actorId: z.ZodString;
+    taskId: z.ZodString;
+    sessionId: z.ZodDefault<z.ZodString>;
+    resources: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+        locator: z.ZodString;
+        scope: z.ZodDefault<z.ZodEnum<["file", "function", "line_range"]>>;
+        functionName: z.ZodOptional<z.ZodString>;
+        lineRange: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            start: number;
+            end: number;
+        }, {
+            start: number;
+            end: number;
+        }>>;
+        metadata: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        locator: string;
+        scope: "function" | "file" | "line_range";
+        metadata: string;
+        id?: string | undefined;
+        functionName?: string | undefined;
+        lineRange?: {
+            start: number;
+            end: number;
+        } | undefined;
+    }, {
+        type: string;
+        locator: string;
+        id?: string | undefined;
+        scope?: "function" | "file" | "line_range" | undefined;
+        functionName?: string | undefined;
+        lineRange?: {
+            start: number;
+            end: number;
+        } | undefined;
+        metadata?: string | undefined;
+    }>, "many">;
+    mode: z.ZodNativeEnum<typeof ResourceClaimMode>;
+    status: z.ZodNativeEnum<typeof ResourceClaimStatus>;
+    createdAt: z.ZodString;
+    releasedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: ResourceClaimStatus;
+    id: string;
+    actorId: string;
+    taskId: string;
+    sessionId: string;
+    resources: {
+        type: string;
+        locator: string;
+        scope: "function" | "file" | "line_range";
+        metadata: string;
+        id?: string | undefined;
+        functionName?: string | undefined;
+        lineRange?: {
+            start: number;
+            end: number;
+        } | undefined;
+    }[];
+    mode: ResourceClaimMode;
+    createdAt: string;
+    releasedAt: string;
+}, {
+    status: ResourceClaimStatus;
+    id: string;
+    actorId: string;
+    taskId: string;
+    resources: {
+        type: string;
+        locator: string;
+        id?: string | undefined;
+        scope?: "function" | "file" | "line_range" | undefined;
+        functionName?: string | undefined;
+        lineRange?: {
+            start: number;
+            end: number;
+        } | undefined;
+        metadata?: string | undefined;
+    }[];
+    mode: ResourceClaimMode;
+    createdAt: string;
+    releasedAt: string;
+    sessionId?: string | undefined;
+}>;
+export type ResourceClaim = z.infer<typeof ResourceClaimSchema>;
+export declare const ResourceClaimCreateSchema: z.ZodObject<{
+    actorId: z.ZodString;
+    taskId: z.ZodString;
+    sessionId: z.ZodOptional<z.ZodString>;
+    resources: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodOptional<z.ZodString>;
+        locator: z.ZodString;
+        scope: z.ZodDefault<z.ZodEnum<["file", "function", "line_range"]>>;
+        functionName: z.ZodOptional<z.ZodString>;
+        lineRange: z.ZodOptional<z.ZodObject<{
+            start: z.ZodNumber;
+            end: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            start: number;
+            end: number;
+        }, {
+            start: number;
+            end: number;
+        }>>;
+        metadata: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        locator: string;
+        scope: "function" | "file" | "line_range";
+        metadata: string;
+        id?: string | undefined;
+        functionName?: string | undefined;
+        lineRange?: {
+            start: number;
+            end: number;
+        } | undefined;
+    }, {
+        type: string;
+        locator: string;
+        id?: string | undefined;
+        scope?: "function" | "file" | "line_range" | undefined;
+        functionName?: string | undefined;
+        lineRange?: {
+            start: number;
+            end: number;
+        } | undefined;
+        metadata?: string | undefined;
+    }>, "many">;
+    mode: z.ZodDefault<z.ZodNativeEnum<typeof ResourceClaimMode>>;
+}, "strip", z.ZodTypeAny, {
+    actorId: string;
+    taskId: string;
+    resources: {
+        type: string;
+        locator: string;
+        scope: "function" | "file" | "line_range";
+        metadata: string;
+        id?: string | undefined;
+        functionName?: string | undefined;
+        lineRange?: {
+            start: number;
+            end: number;
+        } | undefined;
+    }[];
+    mode: ResourceClaimMode;
+    sessionId?: string | undefined;
+}, {
+    actorId: string;
+    taskId: string;
+    resources: {
+        type: string;
+        locator: string;
+        id?: string | undefined;
+        scope?: "function" | "file" | "line_range" | undefined;
+        functionName?: string | undefined;
+        lineRange?: {
+            start: number;
+            end: number;
+        } | undefined;
+        metadata?: string | undefined;
+    }[];
+    sessionId?: string | undefined;
+    mode?: ResourceClaimMode | undefined;
+}>;
+export type ResourceClaimCreate = z.infer<typeof ResourceClaimCreateSchema>;
+export interface ResourceConflict {
+    /** The resource locators that overlap */
+    overlappingLocator: string;
+    resourceType: string;
+    claimA: ResourceClaim;
+    claimB: ResourceClaim;
+    /** True when at least one side is EXCLUSIVE */
+    isHardConflict: boolean;
+}
+/**
+ * A ResourceMatcher knows how to determine overlap between two
+ * locators of the same resource type.  Plugins register matchers
+ * so that core conflict detection can delegate to type-specific logic.
+ */
+export interface ResourceMatcher {
+    /** The resource type this matcher handles, e.g. "file". */
+    type: string;
+    /** Return true if locators a and b overlap for this resource type. */
+    locatorsOverlap(a: string, b: string): boolean;
+}
+/**
+ * Register a ResourceMatcher for a given resource type.
+ * Overwrites any previously registered matcher for the same type.
+ */
+export declare function registerResourceMatcher(m: ResourceMatcher): void;
+/**
+ * Get the registered matcher for a resource type, or undefined.
+ */
+export declare function getResourceMatcher(type: string): ResourceMatcher | undefined;
+/**
+ * Clear all registered matchers (for testing).
+ */
+export declare function clearResourceMatcherRegistry(): void;
+/**
+ * Check if two resource refs overlap.
+ * 1. Different types never overlap.
+ * 2. For file-type resources, normalizes locators before comparison.
+ * 3. Delegates to a registered ResourceMatcher for locator-level overlap.
+ * 4. If locators overlap, applies scope refinement:
+ *    - Either scope "file" (default) → overlap (full-file claim covers everything)
+ *    - Both scope "function" → overlap only if same functionName
+ *    - Both scope "line_range" → overlap if line ranges intersect
+ *    - Mixed function/line_range → overlap (conservative)
+ */
+export declare function resourceLocatorsOverlap(a: ResourceRef, b: ResourceRef): boolean;
+/**
+ * Detect conflicts between a set of active resource claims.
+ * Returns all pairs of claims that have overlapping resources.
+ */
+export declare function detectResourceClaimConflicts(claims: ResourceClaim[]): ResourceConflict[];
+//# sourceMappingURL=resource.d.ts.map

package/dist/kernel/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../_build/src/kernel/resource.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;GAEG;AACH,eAAO,MAAM,aAAa,+CAA6C,CAAC;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,eAAO,MAAM,eAAe;;;;;;;;;EAG1B,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQ5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAI5D,oBAAY,mBAAmB;IAC7B,MAAM,WAAW;IACjB,QAAQ,aAAa;CACtB;AAED,oBAAY,iBAAiB;IAC3B,SAAS,cAAc;IACvB,MAAM,WAAW;CAClB;AAID,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAU9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMpC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAI5E,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,+CAA+C;IAC/C,cAAc,EAAE,OAAO,CAAC;CACzB;AAID;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAChD;AAID;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,eAAe,GAAG,IAAI,CAEhE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAE5E;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACrC,CAAC,EAAE,WAAW,EACd,CAAC,EAAE,WAAW,GACb,OAAO,CAkBT;AA+BD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,gBAAgB,EAAE,CA+BxF"}

package/dist/kernel/resource.js

@@ -0,0 +1,165 @@
+/**
+ * Resource — generic resource reference and claim protocol.
+ *
+ * Provides pluggable locator overlap detection via ResourceMatcher.
+ * Plugins register matchers for specific resource types (e.g. "file");
+ * unknown types fall back to exact locator equality.
+ */
+import { z } from "zod";
+import { normalizeResourcePath } from "./path-normalize.js";
+// ── ResourceRef ────────────────────────────────────
+/**
+ * A reference to any addressable resource in the project.
+ */
+export const ResourceScope = z.enum(["file", "function", "line_range"]);
+export const LineRangeSchema = z.object({
+    start: z.number().int().min(0),
+    end: z.number().int().min(0),
+});
+export const ResourceRefSchema = z.object({
+    type: z.string().min(1),
+    id: z.string().optional(),
+    locator: z.string().min(1),
+    scope: ResourceScope.default("file"),
+    functionName: z.string().optional(),
+    lineRange: LineRangeSchema.optional(),
+    metadata: z.string().default(""),
+});
+// ── Claim Status / Mode ────────────────────────────
+export var ResourceClaimStatus;
+(function (ResourceClaimStatus) {
+    ResourceClaimStatus["ACTIVE"] = "ACTIVE";
+    ResourceClaimStatus["RELEASED"] = "RELEASED";
+})(ResourceClaimStatus || (ResourceClaimStatus = {}));
+export var ResourceClaimMode;
+(function (ResourceClaimMode) {
+    ResourceClaimMode["EXCLUSIVE"] = "exclusive";
+    ResourceClaimMode["SHARED"] = "shared";
+})(ResourceClaimMode || (ResourceClaimMode = {}));
+// ── ResourceClaim ──────────────────────────────────
+export const ResourceClaimSchema = z.object({
+    id: z.string(),
+    actorId: z.string(),
+    taskId: z.string(),
+    sessionId: z.string().default(""),
+    resources: z.array(ResourceRefSchema),
+    mode: z.nativeEnum(ResourceClaimMode),
+    status: z.nativeEnum(ResourceClaimStatus),
+    createdAt: z.string(),
+    releasedAt: z.string(),
+});
+export const ResourceClaimCreateSchema = z.object({
+    actorId: z.string(),
+    taskId: z.string(),
+    sessionId: z.string().optional(),
+    resources: z.array(ResourceRefSchema).min(1),
+    mode: z.nativeEnum(ResourceClaimMode).default(ResourceClaimMode.EXCLUSIVE),
+});
+const _matchers = new Map();
+/**
+ * Register a ResourceMatcher for a given resource type.
+ * Overwrites any previously registered matcher for the same type.
+ */
+export function registerResourceMatcher(m) {
+    _matchers.set(m.type, m);
+}
+/**
+ * Get the registered matcher for a resource type, or undefined.
+ */
+export function getResourceMatcher(type) {
+    return _matchers.get(type);
+}
+/**
+ * Clear all registered matchers (for testing).
+ */
+export function clearResourceMatcherRegistry() {
+    _matchers.clear();
+}
+// ── Pure functions ─────────────────────────────────
+/**
+ * Check if two resource refs overlap.
+ * 1. Different types never overlap.
+ * 2. For file-type resources, normalizes locators before comparison.
+ * 3. Delegates to a registered ResourceMatcher for locator-level overlap.
+ * 4. If locators overlap, applies scope refinement:
+ *    - Either scope "file" (default) → overlap (full-file claim covers everything)
+ *    - Both scope "function" → overlap only if same functionName
+ *    - Both scope "line_range" → overlap if line ranges intersect
+ *    - Mixed function/line_range → overlap (conservative)
+ */
+export function resourceLocatorsOverlap(a, b) {
+    // Different resource types never overlap
+    if (a.type !== b.type)
+        return false;
+    // Normalize file-type locators for consistent comparison
+    const locA = a.type === "file" ? normalizeResourcePath(a.locator) : a.locator;
+    const locB = b.type === "file" ? normalizeResourcePath(b.locator) : b.locator;
+    // Locator-level overlap check (delegates to matcher or exact match)
+    const matcher = _matchers.get(a.type);
+    const locatorsOverlap = matcher
+        ? matcher.locatorsOverlap(locA, locB)
+        : locA === locB;
+    if (!locatorsOverlap)
+        return false;
+    // Scope refinement: if locators overlap, check sub-file granularity
+    return scopesOverlap(a, b);
+}
+/**
+ * Determine if two ResourceRefs with overlapping locators also overlap at scope level.
+ * If either ref claims the whole file (scope "file"), they overlap.
+ * Otherwise, check function/line_range granularity.
+ */
+function scopesOverlap(a, b) {
+    const sa = a.scope;
+    const sb = b.scope;
+    // Either side claims the whole file → overlap
+    if (sa === "file" || sb === "file")
+        return true;
+    // Both function-scoped → overlap only if same function
+    if (sa === "function" && sb === "function") {
+        return a.functionName === b.functionName;
+    }
+    // Both line-range-scoped → overlap if ranges intersect
+    if (sa === "line_range" && sb === "line_range") {
+        const ra = a.lineRange;
+        const rb = b.lineRange;
+        if (!ra || !rb)
+            return true; // missing range info → conservative overlap
+        return ra.start <= rb.end && rb.start <= ra.end;
+    }
+    // Mixed function/line_range → conservative overlap
+    return true;
+}
+/**
+ * Detect conflicts between a set of active resource claims.
+ * Returns all pairs of claims that have overlapping resources.
+ */
+export function detectResourceClaimConflicts(claims) {
+    const active = claims.filter(c => c.status === ResourceClaimStatus.ACTIVE);
+    const conflicts = [];
+    for (let i = 0; i < active.length; i++) {
+        for (let j = i + 1; j < active.length; j++) {
+            const a = active[i];
+            const b = active[j];
+            // Same actor on same task — not a conflict
+            if (a.actorId === b.actorId && a.taskId === b.taskId)
+                continue;
+            for (const ra of a.resources) {
+                for (const rb of b.resources) {
+                    if (resourceLocatorsOverlap(ra, rb)) {
+                        conflicts.push({
+                            overlappingLocator: `${ra.locator} ↔ ${rb.locator}`,
+                            resourceType: ra.type,
+                            claimA: a,
+                            claimB: b,
+                            isHardConflict: a.mode === ResourceClaimMode.EXCLUSIVE ||
+                                b.mode === ResourceClaimMode.EXCLUSIVE,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return conflicts;
+}
+//# sourceMappingURL=resource.js.map