@schnick371/devsteps-shared 0.8.4 → 1.0.0-next.2

package/dist/schemas/analysis.js

@@ -0,0 +1,138 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Context Budget Protocol (CBP) — Analysis Schemas
+ * Zod schemas for T3 archaeology and analysis envelope files.
+ *
+ * @see EPIC-027 CBP Tier-3 Analysis Tools
+ */
+import { z } from 'zod';
+/**
+ * Context Budget Protocol (CBP) — Analysis Schemas
+ *
+ * Defines structured JSON envelopes for AI agent-to-agent handoffs.
+ * Aspect agents write AnalysisBriefing to disk (.devsteps/analysis/[ID]/)
+ * and return CompressedVerdict envelopes (~150 tokens) in-memory to the coordinator.
+ *
+ * @see EPIC-027 Context Budget Protocol Infrastructure
+ */
+// ─── Aspect types ────────────────────────────────────────────────────────────
+export const AnalysisAspect = z.enum([
+    'impact',
+    'constraints',
+    'quality',
+    'staleness',
+    'integration',
+    'internal', // competitive analyst: codebase
+    'web', // competitive analyst: internet
+    'meta', // coordinator judge verdict
+]);
+// ─── Verdict types ───────────────────────────────────────────────────────────
+export const AspectVerdict = z.enum([
+    'PROCEED',
+    'PROCEED-WITH-CAUTION',
+    'STOP',
+    // staleness-specific
+    'CURRENT',
+    'STALE-PARTIAL',
+    'STALE-OBSOLETE',
+    'STALE-CONFLICT',
+]);
+// ─── CompressedVerdict ───────────────────────────────────────────────────────
+/**
+ * Compressed envelope returned IN-MEMORY by aspect agents to the coordinator.
+ * Max ~150 tokens — coordinator reads only this, never the full report.
+ */
+export const CompressedVerdictSchema = z.object({
+    /** Which aspect produced this envelope */
+    aspect: AnalysisAspect,
+    /** Proceed / stop / caution signal */
+    verdict: AspectVerdict,
+    /** 0.0–1.0 confidence in the verdict */
+    confidence: z.number().min(0).max(1),
+    /** Max 3, max 100 chars each — the coordinator reads these */
+    top3_findings: z.array(z.string().max(200)).max(3),
+    /** Relative path to the full AnalysisBriefing JSON on disk */
+    report_path: z.string(),
+    /** ISO 8601 timestamp */
+    timestamp: z.string().datetime(),
+    // ── Competitive mode fields (aspect = 'internal' | 'web' | 'meta') ───────
+    /** Winner agent name (meta verdict only) */
+    winner: z.string().optional(),
+    /** Rule applied by the judge (meta verdict only) */
+    rule_applied: z.string().optional(),
+    /** Path to winning implementation briefing (meta verdict only) */
+    implementation_briefing: z.string().optional(),
+    /** Internet advantage claim (web analyst only) */
+    internet_advantage_claim: z.string().optional(),
+    /** Arbitrary aspect-specific scalar fields (kept minimal) */
+    metadata: z.record(z.string(), z.unknown()).default({}),
+});
+// ─── AnalysisBriefing ────────────────────────────────────────────────────────
+/**
+ * Full analysis report written to disk by aspect agents.
+ * Path: `.devsteps/analysis/[TASK-ID]/[aspect]-report.json`
+ * Contains the CompressedVerdict envelope + full markdown analysis text.
+ * Impl-subagent reads this for implementation context.
+ */
+export const AnalysisBriefingSchema = z.object({
+    /** DevSteps item ID this analysis belongs to */
+    task_id: z.string().regex(/^(EPIC|STORY|TASK|REQ|FEAT|BUG|SPIKE|TEST)-\d{3,}$/),
+    /** Which aspect this briefing covers */
+    aspect: AnalysisAspect,
+    /** Name of the agent that produced this briefing */
+    analyst: z.string(),
+    /** When the briefing was created */
+    created: z.string().datetime(),
+    /** The compressed envelope (also returned in-memory to coordinator) */
+    envelope: CompressedVerdictSchema,
+    /** Full markdown analysis text for implementation agents to read */
+    full_analysis: z.string(),
+    /** Files identified as affected by this analysis */
+    affected_files: z.array(z.string()).default([]),
+    /** Prioritized action recommendations */
+    recommendations: z.array(z.string()).default([]),
+    /** Schema version for forward compatibility */
+    schema_version: z.literal('1.0').default('1.0'),
+});
+// ─── SprintVerdict ───────────────────────────────────────────────────────────
+/**
+ * Meta-verdict written by the coordinator judge in Competitive Mode.
+ * Path: `.devsteps/analysis/[TASK-ID]/meta.json`
+ */
+export const SprintVerdictSchema = z.object({
+    task_id: z.string(),
+    mode: z.literal('competitive'),
+    winner: z.enum(['devsteps-analyst-internal-subagent', 'devsteps-analyst-web-subagent']),
+    rule_applied: z.enum(['RULE 1', 'RULE 2', 'RULE 3', 'RULE 4', 'RULE 5']),
+    implementation_briefing: z.string(),
+    flags: z.array(z.string()).default([]),
+    created: z.string().datetime(),
+    schema_version: z.literal('1.0').default('1.0'),
+});
+// ─── EnrichedSprintBrief ─────────────────────────────────────────────────────
+/**
+ * Produced by devsteps-planner at sprint start from global archaeology + backlog.
+ * Path: `.devsteps/analysis/sprint-[DATE]/enriched-sprint-brief.json`
+ */
+export const SprintItemRisk = z.enum(['QUICK', 'STANDARD', 'FULL', 'COMPETITIVE']);
+export const EnrichedSprintItemSchema = z.object({
+    item_id: z.string(),
+    title: z.string(),
+    risk: SprintItemRisk,
+    estimated_minutes: z.number().optional(),
+    affected_files: z.array(z.string()).default([]),
+    depends_on: z.array(z.string()).default([]),
+    shared_file_conflicts: z.array(z.string()).default([]),
+    notes: z.string().optional(),
+});
+export const EnrichedSprintBriefSchema = z.object({
+    sprint_date: z.string(),
+    global_context_path: z.string(),
+    ordered_items: z.array(EnrichedSprintItemSchema),
+    invalidation_cache: z.array(z.string()).default([]),
+    created: z.string().datetime(),
+    schema_version: z.literal('1.0').default('1.0'),
+});
+//# sourceMappingURL=analysis.js.map

package/dist/schemas/analysis.js.map

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

package/dist/schemas/cbp-loops.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Context Budget Protocol (CBP) — Loop Control Schemas
+ * Zod schemas for rejection feedback, iteration signals, and escalation.
+ *
+ * @see EPIC-028 CBP Tier-2 Mandate Tools
+ */
+import { z } from 'zod';
+/**
+ * Context Budget Protocol (CBP) — Loop Control Schemas
+ *
+ * These schemas enable bounded loops across all tiers without infinite recursion.
+ * Every loop MUST have a hard termination bound enforced in the handler.
+ *
+ * Loop types:
+ * - TDD inner loop: test → impl → test (max 3 iterations, Tier-3)
+ * - Review-Fix loop: review → rejection → impl → review (max 3 iterations, Tier-2↔Tier-3)
+ * - Clarification loop: research → ambiguity → re-research (max 2 iterations, Tier-2)
+ * - Adaptive replanning: every 5 items or on risk drift (max once per 5 items, Tier-1)
+ *
+ * @see EPIC-028 N-Tier Agent Hierarchy
+ * @see STORY-108 MandateResult CBP Extension
+ * @see SPIKE-015 Tier-4 + Loop Pattern Formalization
+ */
+export declare const LoopType: z.ZodEnum<{
+    tdd: "tdd";
+    "review-fix": "review-fix";
+    clarification: "clarification";
+    replanning: "replanning";
+}>;
+export type LoopType = z.infer<typeof LoopType>;
+export declare const LoopStatus: z.ZodEnum<{
+    continuing: "continuing";
+    resolved: "resolved";
+    exhausted: "exhausted";
+    escalated: "escalated";
+}>;
+export type LoopStatus = z.infer<typeof LoopStatus>;
+/**
+ * Written by deep-analyst-quality (Tier-2) when a Tier-3 implementation
+ * fails the quality gate. Tier-1 reads this and re-dispatches the Tier-3
+ * impl agent with the rejection context attached.
+ *
+ * Storage: .devsteps/cbp/[sprint_id]/[item_id].rejection-[iteration].json
+ * Iteration files are append-only (never overwrite) for audit trail.
+ */
+export declare const RejectionIssueSchema: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodOptional<z.ZodNumber>;
+    issue: z.ZodString;
+    suggestion: z.ZodString;
+}, z.core.$strip>;
+export type RejectionIssue = z.infer<typeof RejectionIssueSchema>;
+export declare const RejectionType: z.ZodEnum<{
+    "quality-insufficient": "quality-insufficient";
+    "wrong-approach": "wrong-approach";
+    "missing-requirement": "missing-requirement";
+    "test-failure": "test-failure";
+    "type-error": "type-error";
+}>;
+export type RejectionType = z.infer<typeof RejectionType>;
+export declare const RejectionFeedbackSchema: z.ZodObject<{
+    target_subagent: z.ZodString;
+    iteration: z.ZodNumber;
+    rejection_type: z.ZodEnum<{
+        "quality-insufficient": "quality-insufficient";
+        "wrong-approach": "wrong-approach";
+        "missing-requirement": "missing-requirement";
+        "test-failure": "test-failure";
+        "type-error": "type-error";
+    }>;
+    violated_criteria: z.ZodArray<z.ZodString>;
+    specific_issues: z.ZodArray<z.ZodObject<{
+        file: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+        issue: z.ZodString;
+        suggestion: z.ZodString;
+    }, z.core.$strip>>;
+    max_iterations_remaining: z.ZodNumber;
+    escalate_if_remaining: z.ZodDefault<z.ZodNumber>;
+    sprint_id: z.ZodString;
+    item_id: z.ZodString;
+    created_at: z.ZodString;
+    schema_version: z.ZodDefault<z.ZodLiteral<"1.0">>;
+}, z.core.$strip>;
+export type RejectionFeedback = z.infer<typeof RejectionFeedbackSchema>;
+/**
+ * Written by any agent in a loop to signal the current loop state to Tier-1.
+ * Tier-1 checks this file before each iteration to detect stuck/resolved loops.
+ *
+ * Storage: .devsteps/cbp/[sprint_id]/[item_id].loop-signal.json
+ * OVERWRITES previous signal — represents CURRENT state (not history).
+ * Use iteration field to reconstruct history if needed.
+ */
+export declare const IterationSignalSchema: z.ZodObject<{
+    loop_type: z.ZodEnum<{
+        tdd: "tdd";
+        "review-fix": "review-fix";
+        clarification: "clarification";
+        replanning: "replanning";
+    }>;
+    status: z.ZodEnum<{
+        continuing: "continuing";
+        resolved: "resolved";
+        exhausted: "exhausted";
+        escalated: "escalated";
+    }>;
+    iteration: z.ZodNumber;
+    max_iterations: z.ZodNumber;
+    sprint_id: z.ZodString;
+    item_id: z.ZodString;
+    notes: z.ZodOptional<z.ZodString>;
+    signaled_at: z.ZodString;
+    schema_version: z.ZodDefault<z.ZodLiteral<"1.0">>;
+}, z.core.$strip>;
+export type IterationSignal = z.infer<typeof IterationSignalSchema>;
+/**
+ * Written by any agent (any tier) when it cannot proceed without external input.
+ * Tier-1 checks for pending escalations before each phase.
+ * Escalations PAUSE execution — never silently continue.
+ *
+ * Storage: .devsteps/cbp/[sprint_id]/escalations/[escalation_id].json
+ * Files are NOT overwritten — each escalation gets a unique ID.
+ */
+export declare const EscalationType: z.ZodEnum<{
+    "human-required": "human-required";
+    "contradicting-requirements": "contradicting-requirements";
+    "budget-exhausted": "budget-exhausted";
+    "architectural-decision": "architectural-decision";
+    "scope-ambiguous": "scope-ambiguous";
+}>;
+export type EscalationType = z.infer<typeof EscalationType>;
+export declare const EscalationSignalSchema: z.ZodObject<{
+    escalation_id: z.ZodString;
+    source_agent: z.ZodString;
+    escalation_type: z.ZodEnum<{
+        "human-required": "human-required";
+        "contradicting-requirements": "contradicting-requirements";
+        "budget-exhausted": "budget-exhausted";
+        "architectural-decision": "architectural-decision";
+        "scope-ambiguous": "scope-ambiguous";
+    }>;
+    context: z.ZodString;
+    decision_needed: z.ZodString;
+    blocking_items: z.ZodArray<z.ZodString>;
+    suggested_resolution: z.ZodOptional<z.ZodString>;
+    sprint_id: z.ZodString;
+    escalated_at: z.ZodString;
+    schema_version: z.ZodDefault<z.ZodLiteral<"1.0">>;
+}, z.core.$strip>;
+export type EscalationSignal = z.infer<typeof EscalationSignalSchema>;
+//# sourceMappingURL=cbp-loops.d.ts.map

package/dist/schemas/cbp-loops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cbp-loops.d.ts","sourceRoot":"","sources":["../../src/schemas/cbp-loops.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;GAeG;AAIH,eAAO,MAAM,QAAQ;;;;;EAKnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,eAAO,MAAM,UAAU;;;;;EAKrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAIpD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB;;;;;iBAS/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,eAAO,MAAM,aAAa;;;;;;EAMxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;iBAuBlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;iBAmBhC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAIpE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;EAMzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;iBAwBjC,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/schemas/cbp-loops.js

@@ -0,0 +1,160 @@
+/**
+ * Copyright © 2025 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Context Budget Protocol (CBP) — Loop Control Schemas
+ * Zod schemas for rejection feedback, iteration signals, and escalation.
+ *
+ * @see EPIC-028 CBP Tier-2 Mandate Tools
+ */
+import { z } from 'zod';
+/**
+ * Context Budget Protocol (CBP) — Loop Control Schemas
+ *
+ * These schemas enable bounded loops across all tiers without infinite recursion.
+ * Every loop MUST have a hard termination bound enforced in the handler.
+ *
+ * Loop types:
+ * - TDD inner loop: test → impl → test (max 3 iterations, Tier-3)
+ * - Review-Fix loop: review → rejection → impl → review (max 3 iterations, Tier-2↔Tier-3)
+ * - Clarification loop: research → ambiguity → re-research (max 2 iterations, Tier-2)
+ * - Adaptive replanning: every 5 items or on risk drift (max once per 5 items, Tier-1)
+ *
+ * @see EPIC-028 N-Tier Agent Hierarchy
+ * @see STORY-108 MandateResult CBP Extension
+ * @see SPIKE-015 Tier-4 + Loop Pattern Formalization
+ */
+// ─── Loop Types ───────────────────────────────────────────────────────────────
+export const LoopType = z.enum([
+    'tdd', // Red-Green-Refactor inner loop
+    'review-fix', // Reviewer rejects → impl agent fixes → reviewer re-checks
+    'clarification', // Analyst encounters ambiguity → requests clarification
+    'replanning', // Sprint executor replans after accumulated drift
+]);
+export const LoopStatus = z.enum([
+    'continuing', // Loop will execute another iteration
+    'resolved', // Loop terminated with success
+    'exhausted', // Max iterations reached without resolution
+    'escalated', // Loop escalated to human or higher tier
+]);
+// ─── RejectionFeedbackSchema ──────────────────────────────────────────────────
+/**
+ * Written by deep-analyst-quality (Tier-2) when a Tier-3 implementation
+ * fails the quality gate. Tier-1 reads this and re-dispatches the Tier-3
+ * impl agent with the rejection context attached.
+ *
+ * Storage: .devsteps/cbp/[sprint_id]/[item_id].rejection-[iteration].json
+ * Iteration files are append-only (never overwrite) for audit trail.
+ */
+export const RejectionIssueSchema = z.object({
+    /** Relative file path where the issue was found */
+    file: z.string(),
+    /** Line number (optional — for precise targeting) */
+    line: z.number().int().positive().optional(),
+    /** Human-readable description of the issue */
+    issue: z.string().max(300),
+    /** Concrete suggestion for the impl agent to fix */
+    suggestion: z.string().max(300),
+});
+export const RejectionType = z.enum([
+    'quality-insufficient', // Score too low, general quality issues
+    'wrong-approach', // Architectural or pattern decision is wrong
+    'missing-requirement', // One or more acceptance criteria not met
+    'test-failure', // Tests fail (TypeScript errors, assertion failures)
+    'type-error', // TypeScript strict mode violations
+]);
+export const RejectionFeedbackSchema = z.object({
+    /** Which Tier-3 agent produced the rejected output */
+    target_subagent: z.string(),
+    /** Current loop iteration (1-based) */
+    iteration: z.number().int().min(1).max(5),
+    /** Classification of the rejection reason */
+    rejection_type: RejectionType,
+    /** Which acceptance criteria from the story/task were violated */
+    violated_criteria: z.array(z.string()).min(1),
+    /** Specific, actionable issues for the impl agent */
+    specific_issues: z.array(RejectionIssueSchema).min(1).max(20),
+    /** How many more iterations remain (countdown) */
+    max_iterations_remaining: z.number().int().min(0).max(4),
+    /** If remaining iterations ≤ this value, escalate instead of retrying */
+    escalate_if_remaining: z.number().int().min(0).max(3).default(0),
+    /** Sprint ID for file path construction */
+    sprint_id: z.string(),
+    /** Which DevSteps item this rejection applies to */
+    item_id: z.string(),
+    /** ISO 8601 timestamp */
+    created_at: z.string().datetime(),
+    /** Schema version */
+    schema_version: z.literal('1.0').default('1.0'),
+});
+// ─── IterationSignalSchema ────────────────────────────────────────────────────
+/**
+ * Written by any agent in a loop to signal the current loop state to Tier-1.
+ * Tier-1 checks this file before each iteration to detect stuck/resolved loops.
+ *
+ * Storage: .devsteps/cbp/[sprint_id]/[item_id].loop-signal.json
+ * OVERWRITES previous signal — represents CURRENT state (not history).
+ * Use iteration field to reconstruct history if needed.
+ */
+export const IterationSignalSchema = z.object({
+    /** Which loop type is signaling */
+    loop_type: LoopType,
+    /** Current loop state */
+    status: LoopStatus,
+    /** Current iteration number (1-based) */
+    iteration: z.number().int().min(1),
+    /** Hard maximum — never execute iteration > max_iterations */
+    max_iterations: z.number().int().min(1).max(5),
+    /** Sprint ID for file path construction */
+    sprint_id: z.string(),
+    /** Which DevSteps item this loop is for */
+    item_id: z.string(),
+    /** Optional context for debugging or escalation messages */
+    notes: z.string().max(500).optional(),
+    /** ISO 8601 timestamp of this signal */
+    signaled_at: z.string().datetime(),
+    /** Schema version */
+    schema_version: z.literal('1.0').default('1.0'),
+});
+// ─── EscalationSignalSchema ───────────────────────────────────────────────────
+/**
+ * Written by any agent (any tier) when it cannot proceed without external input.
+ * Tier-1 checks for pending escalations before each phase.
+ * Escalations PAUSE execution — never silently continue.
+ *
+ * Storage: .devsteps/cbp/[sprint_id]/escalations/[escalation_id].json
+ * Files are NOT overwritten — each escalation gets a unique ID.
+ */
+export const EscalationType = z.enum([
+    'human-required', // Cannot continue without user decision
+    'contradicting-requirements', // Two requirements conflict (needs user priority)
+    'budget-exhausted', // Token or time budget depleted
+    'architectural-decision', // Requires architecture choice beyond agent scope
+    'scope-ambiguous', // Acceptance criteria are genuinely unclear
+]);
+export const EscalationSignalSchema = z.object({
+    /** Unique ID for this escalation — used as filename */
+    escalation_id: z.string().uuid(),
+    /** Which agent triggered the escalation */
+    source_agent: z.string(),
+    /** Classification of what decision is needed */
+    escalation_type: EscalationType,
+    /**
+     * What led to this escalation — max ~400 tokens.
+     * Must be self-contained (no file path references — Tier-1 reads this inline).
+     */
+    context: z.string().max(3000),
+    /** Specific yes/no or choice question for the human or Tier-1 */
+    decision_needed: z.string().max(500),
+    /** DevSteps item IDs blocked by this escalation */
+    blocking_items: z.array(z.string()).min(1),
+    /** What the agent suggests (included but not authoritative) */
+    suggested_resolution: z.string().max(500).optional(),
+    /** Sprint ID for file path construction */
+    sprint_id: z.string(),
+    /** ISO 8601 timestamp */
+    escalated_at: z.string().datetime(),
+    /** Schema version */
+    schema_version: z.literal('1.0').default('1.0'),
+});
+//# sourceMappingURL=cbp-loops.js.map

package/dist/schemas/cbp-loops.js.map

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

package/dist/schemas/cbp-loops.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Unit Tests for CBP Loop Control Schemas
+ *
+ * Tests: RejectionFeedbackSchema, IterationSignalSchema, EscalationSignalSchema
+ *
+ * @see STORY-108 MandateResult CBP Extension
+ * @see TASK-234 Loop schemas: RejectionFeedback + IterationSignal + EscalationSignal
+ */
+export {};
+//# sourceMappingURL=cbp-loops.test.d.ts.map

package/dist/schemas/cbp-loops.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cbp-loops.test.d.ts","sourceRoot":"","sources":["../../src/schemas/cbp-loops.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}