@cleocode/contracts 2026.9.20 → 2026.9.22

package/dist/decide.js

@@ -0,0 +1,184 @@
+/**
+ * Typed-decision contracts — provider-neutral domain types and zod schemas.
+ *
+ * A *typed decision* asks a decision model a set of named questions about a
+ * piece of state and receives, for every question, a calibrated probability
+ * distribution over the admissible answers plus a confidence score. Three
+ * question shapes exist:
+ *
+ * - `noul`   — a yes/no question; the answer is a probability that it holds.
+ * - `choice` — pick one of several named options.
+ * - `score`  — place the state on an ordered scale of 2–10 levels.
+ *
+ * These types describe the DOMAIN, not any one vendor's wire format. Provider
+ * adapters (in `packages/core/`) translate between these shapes and their
+ * transport; nothing here names a provider.
+ *
+ * This file is types + zod schemas + const data only (arch gate 10,
+ * `scripts/lint-no-runtime-in-contracts.mjs`). Validation entry points are the
+ * exported `*Schema` values; call `.parse()` / `.safeParse()` on them.
+ *
+ * @task T12489
+ * @epic T12486
+ */
+import { z } from 'zod';
+// ─── Const data ───────────────────────────────────────────────────────────────
+/** Every supported decision-question shape, in canonical order. */
+export const DECISION_QUESTION_TYPES = ['noul', 'choice', 'score'];
+/**
+ * Where a {@link DecisionOutcome} came from.
+ *
+ * - `provider` — answered live by a decision provider.
+ * - `cache`    — replayed from a previously stored provider answer.
+ * - `fallback` — produced locally because no provider answer was available.
+ */
+export const DECISION_OUTCOME_SOURCES = ['provider', 'cache', 'fallback'];
+/**
+ * Hard limits a {@link DecisionRequest} must respect. Enforced by
+ * {@link decisionRequestSchema}.
+ */
+export const DECISION_REQUEST_LIMITS = {
+    /**
+     * Maximum size of `state`, in UTF-16 characters. A string state is measured
+     * directly; a structured (object/array) state is measured on its
+     * `JSON.stringify` serialization, which is what goes over the wire.
+     */
+    maxStateChars: 32_000,
+    /** Minimum number of questions in one request. */
+    minQuestions: 1,
+    /** Maximum number of questions in one request. */
+    maxQuestions: 32,
+    /** Minimum number of options a `choice` question must offer. */
+    minChoiceOptions: 2,
+    /** Minimum number of levels on a `score` question's scale. */
+    minScoreLevels: 2,
+    /** Maximum number of levels on a `score` question's scale. */
+    maxScoreLevels: 10,
+};
+// ─── Zod schemas ──────────────────────────────────────────────────────────────
+/** Zod schema for {@link DecisionQuestionType}. */
+export const decisionQuestionTypeSchema = z.enum(DECISION_QUESTION_TYPES);
+/** Zod schema for {@link DecisionOutcomeSource}. */
+export const decisionOutcomeSourceSchema = z.enum(DECISION_OUTCOME_SOURCES);
+/** Zod schema for {@link DecisionInstructions}. */
+export const decisionInstructionsSchema = z.union([z.string(), z.record(z.string(), z.json())]);
+/** A probability or confidence: a finite number in [0, 1]. */
+const unitIntervalSchema = z.number().min(0).max(1);
+/**
+ * Zod schema for {@link DecisionState}. Rejects a state whose size exceeds
+ * {@link DECISION_REQUEST_LIMITS.maxStateChars} (serialized size for
+ * structured state).
+ */
+export const decisionStateSchema = z
+    .union([z.string(), z.array(z.json()), z.record(z.string(), z.json())])
+    .superRefine((state, context) => {
+    const size = typeof state === 'string' ? state.length : JSON.stringify(state).length;
+    if (size > DECISION_REQUEST_LIMITS.maxStateChars) {
+        context.addIssue({
+            code: 'custom',
+            message: `state is ${size} characters; the limit is ${DECISION_REQUEST_LIMITS.maxStateChars}`,
+        });
+    }
+});
+/** Zod schema for {@link NoulDecisionQuestion}. */
+export const noulDecisionQuestionSchema = z.object({
+    type: z.literal('noul'),
+    instructions: decisionInstructionsSchema.optional(),
+    criteria: z.string().min(1),
+});
+/** Zod schema for {@link ChoiceDecisionQuestion}; requires at least two options. */
+export const choiceDecisionQuestionSchema = z.object({
+    type: z.literal('choice'),
+    instructions: decisionInstructionsSchema.optional(),
+    criteria: z
+        .record(z.string().min(1), z.string())
+        .refine((options) => Object.keys(options).length >= DECISION_REQUEST_LIMITS.minChoiceOptions, {
+        message: `a choice question needs at least ${DECISION_REQUEST_LIMITS.minChoiceOptions} options`,
+    }),
+});
+/** Zod schema for {@link ScoreDecisionQuestion}; requires 2–10 levels. */
+export const scoreDecisionQuestionSchema = z.object({
+    type: z.literal('score'),
+    instructions: decisionInstructionsSchema.optional(),
+    criteria: z
+        .array(z.string())
+        .min(DECISION_REQUEST_LIMITS.minScoreLevels)
+        .max(DECISION_REQUEST_LIMITS.maxScoreLevels),
+});
+/** Zod discriminated-union schema for {@link DecisionQuestion}. */
+export const decisionQuestionSchema = z.discriminatedUnion('type', [
+    noulDecisionQuestionSchema,
+    choiceDecisionQuestionSchema,
+    scoreDecisionQuestionSchema,
+]);
+/**
+ * Zod schema for {@link DecisionRequest}. Enforces every
+ * {@link DECISION_REQUEST_LIMITS} bound: state size, 1–32 questions, ≥ 2
+ * choice options and 2–10 score levels.
+ *
+ * @example
+ * ```ts
+ * decisionRequestSchema.parse({
+ *   state: 'The build failed on a flaky network test.',
+ *   questions: {
+ *     retry: { type: 'noul', criteria: 'Retrying is likely to succeed' },
+ *     severity: { type: 'score', criteria: ['trivial', 'minor', 'major'] },
+ *   },
+ * });
+ * ```
+ */
+export const decisionRequestSchema = z.object({
+    model: z.string().min(1).optional(),
+    state: decisionStateSchema,
+    questions: z.record(z.string().min(1), decisionQuestionSchema).refine((questions) => {
+        const count = Object.keys(questions).length;
+        return (count >= DECISION_REQUEST_LIMITS.minQuestions &&
+            count <= DECISION_REQUEST_LIMITS.maxQuestions);
+    }, {
+        message: `a request needs ${DECISION_REQUEST_LIMITS.minQuestions}–${DECISION_REQUEST_LIMITS.maxQuestions} questions`,
+    }),
+});
+/** Zod schema for {@link NoulDecisionAnswer}. */
+export const noulDecisionAnswerSchema = z.object({
+    type: z.literal('noul'),
+    value: z.boolean(),
+    probability: unitIntervalSchema,
+    confidence: unitIntervalSchema,
+});
+/** Zod schema for {@link ChoiceDecisionAnswer}. */
+export const choiceDecisionAnswerSchema = z.object({
+    type: z.literal('choice'),
+    value: z.string().min(1),
+    probabilities: z.record(z.string().min(1), unitIntervalSchema),
+    confidence: unitIntervalSchema,
+});
+/** Zod schema for {@link ScoreDecisionAnswer}. */
+export const scoreDecisionAnswerSchema = z.object({
+    type: z.literal('score'),
+    value: z.number().int().nonnegative(),
+    probabilities: z
+        .array(unitIntervalSchema)
+        .min(DECISION_REQUEST_LIMITS.minScoreLevels)
+        .max(DECISION_REQUEST_LIMITS.maxScoreLevels),
+    confidence: unitIntervalSchema,
+});
+/** Zod discriminated-union schema for {@link DecisionAnswer}. */
+export const decisionAnswerSchema = z.discriminatedUnion('type', [
+    noulDecisionAnswerSchema,
+    choiceDecisionAnswerSchema,
+    scoreDecisionAnswerSchema,
+]);
+/** Zod schema for {@link DecisionOutcome} (e.g. when reading a cached outcome back). */
+export const decisionOutcomeSchema = z.object({
+    answers: z.record(z.string().min(1), decisionAnswerSchema),
+    source: decisionOutcomeSourceSchema,
+    requestId: z.string().min(1).optional(),
+    latencyMs: z.number().nonnegative(),
+    costUsd: z.number().nonnegative().optional(),
+    inputTokens: z.number().int().nonnegative().optional(),
+});
+/** Zod schema for {@link DecisionProviderConfig}; `baseUrl` must be an absolute URL. */
+export const decisionProviderConfigSchema = z.object({
+    baseUrl: z.url(),
+});
+//# sourceMappingURL=decide.js.map

package/dist/decide.js.map

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

package/dist/dispatch/operations-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"operations-registry.d.ts","sourceRoot":"","sources":["../../src/dispatch/operations-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEjG,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAMvE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAE1F;AAeD,6DAA6D;AAC7D,eAAO,MAAM,UAAU,EAAE,YAAY,EAu3UpC,CAAC"}
+{"version":3,"file":"operations-registry.d.ts","sourceRoot":"","sources":["../../src/dispatch/operations-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAEjG,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;AAMvE;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,EAAE,GAAG,YAAY,EAAE,CAE1F;AAeD,6DAA6D;AAC7D,eAAO,MAAM,UAAU,EAAE,YAAY,EAk7UpC,CAAC"}

package/dist/dispatch/operations-registry.js

@@ -2967,6 +2967,13 @@ export const OPERATIONS = [
                 description: 'Disable automatic parent completion',
                 cli: { flag: 'no-auto-complete' },
             },
+            {
+                name: 'expectedUpdatedAt',
+                type: 'string',
+                required: false,
+                description: 'Optimistic-concurrency guard: fail with E_CONFLICT unless the task updatedAt still equals this value',
+                cli: { flag: 'expected-updated-at' },
+            },
         ],
         inputSchema: tasksUpdateInputContract,
         outputSchema: OUTPUT_CONTRACTS['tasks.update'],
@@ -6750,6 +6757,42 @@ export const OPERATIONS = [
             },
         ],
     },
+    {
+        gateway: 'mutate',
+        domain: 'nexus',
+        operation: 'projects.status',
+        description: 'nexus.projects.status (mutate) — probe and record git state of every project location on this device (bounded, parallel; no network unless fetch)',
+        tier: 1,
+        idempotent: true,
+        sessionRequired: false,
+        requiredParams: [],
+        params: [
+            {
+                name: 'fetch',
+                type: 'boolean',
+                required: false,
+                description: 'Run git fetch per location first (network; off by default)',
+            },
+            {
+                name: 'concurrency',
+                type: 'number',
+                required: false,
+                description: 'Locations probed at once (default 8, max 64)',
+            },
+            {
+                name: 'timeoutMs',
+                type: 'number',
+                required: false,
+                description: 'Per-location git budget in ms (default 10000; 30000 with fetch)',
+            },
+            {
+                name: 'staleAfterMs',
+                type: 'number',
+                required: false,
+                description: 'A fetch older than this marks remote state stale (default 24h)',
+            },
+        ],
+    },
     {
         gateway: 'mutate',
         domain: 'nexus',
@@ -7926,6 +7969,12 @@ export const OPERATIONS = [
             { name: 'title', type: 'string', required: false, description: 'Override PR title' },
             { name: 'body', type: 'string', required: false, description: 'Override PR body' },
             { name: 'base', type: 'string', required: false, description: 'PR base branch' },
+            {
+                name: 'taskId',
+                type: 'string',
+                required: false,
+                description: 'Owning task id (T####) for the PR commit subject',
+            },
         ],
     },
     {
@@ -7959,6 +8008,12 @@ export const OPERATIONS = [
             { name: 'title', type: 'string', required: false, description: 'Override PR title' },
             { name: 'body', type: 'string', required: false, description: 'Override PR body' },
             { name: 'base', type: 'string', required: false, description: 'PR base branch' },
+            {
+                name: 'taskId',
+                type: 'string',
+                required: false,
+                description: 'Owning task id (T####) for the PR commit subject',
+            },
         ],
     },
     {
@@ -8168,6 +8223,7 @@ export const OPERATIONS = [
                 required: false,
                 enum: DOCS_LIFECYCLE_STATUSES,
                 description: 'Override the new lifecycle status. Defaults to "draft" on every update. ' +
+                    'Alone (no file or content) it changes only the lifecycle status. ' +
                     `Valid: ${DOCS_LIFECYCLE_STATUSES.join('|')}.`,
             },
             {