@peasant-labs/schema 0.1.0-rc10

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Peasant Labs
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,66 @@
+# @peasant-labs/schema
+
+Use this package when a TypeScript application needs typed, always-in-sync
+access to the peasant-labs wire contract: the same domain types, closed-set
+enums, and runtime validation Go services already produce and enforce,
+optionally with type-only Local/Village operation contracts for API-aware
+tooling.
+
+TypeScript bindings for the canonical `github.com/peasant-labs/schema` wire
+contract. The package is a contract-only leaf: it contains data definitions,
+runtime Zod schemas, Go-shaped closed-set values and guards, version constants,
+and schema-owned fixture helpers. It does not contain HTTP or WebSocket clients.
+Consumers that need endpoint typing can import type-only OpenAPI `paths` and
+`operations` namespaces from `@peasant-labs/schema/local-api` and
+`@peasant-labs/schema/village-api`; these exports do not contain a transport.
+
+The Go contract and its generated Types OpenAPI document are authoritative.
+Hey API's Zod plugin derives both the TypeScript definitions and runtime schemas
+from that document. `openapi-typescript` derives the Local and Village operation
+contracts from their OpenAPI documents. A small generated facade exposes the
+same closed-set shape as Go (`Role.User`, `AllRoles`, `isRole`) without
+maintaining a handwritten second contract. The retired `@peasant-labs/types`
+package must not receive new wire definitions.
+
+The generated root Zod schemas enforce the wire's structural shape and selected
+generator-owned local cross-field invariants, including association evidence and
+annotation target rules. The Go `Validate` methods remain authoritative at the
+trust boundary for payload-context and cross-object relationships. TypeScript
+consumer adapters remain responsible for any post-parse semantic handling.
+
+`ProjectHash` is a nominal string identity matching Go's validated newtype.
+Construct values with `newProjectHash`, narrow unknown wire values with
+`isProjectHash`, or assert a trust boundary with `validateProjectHash`.
+
+This package is published to npm as `@peasant-labs/schema`. The committed
+`package.json` in this directory stays `0.0.0-development` + `private: true` as
+a local safety; the schema module's release pipeline stamps the real version
+from the module release tag (not an individual OpenAPI document version) and
+publishes at release time, so every published version corresponds to a tagged
+schema module release. An `-rcN` tag publishes under the npm dist-tag `next`; a
+final `vX.Y.Z` publishes under `latest`.
+
+```ts
+import {
+  Role,
+  isRole,
+  newProjectHash,
+  zSessionDetailPayload,
+  type SessionDetailPayload,
+} from "@peasant-labs/schema";
+import { loadCorpus } from "@peasant-labs/schema/testcase";
+import { loadQualityFixtures, qualitySessions } from "@peasant-labs/schema/fixtures/quality";
+import { loadTimelineFixtures } from "@peasant-labs/schema/fixtures/timeline";
+import type { operations as LocalOperations } from "@peasant-labs/schema/local-api";
+
+const detail: SessionDetailPayload = zSessionDetailPayload.parse(input);
+type SessionDetailResponse = LocalOperations["getSession"]["responses"][200]["content"]["application/json"];
+const fixtures = loadQualityFixtures();
+const timeline = loadTimelineFixtures();
+qualitySessions(fixtures);
+timeline.cases.length;
+isRole(Role.User);
+newProjectHash("a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2");
+const response: SessionDetailResponse = detail;
+void response;
+```

package/dist/fixtures/quality.d.ts

@@ -0,0 +1,81 @@
+import type { QualitySession } from "../index.js";
+export declare const QualityFixtureName: Readonly<{
+    readonly ResolvedTypical: "resolved_typical";
+    readonly ResolvedHighTokens: "resolved_high_tokens";
+    readonly PartialMedium: "partial_medium";
+    readonly FailedComplex: "failed_complex";
+    readonly ResolvedMinimal: "resolved_minimal";
+}>;
+export type QualityFixtureName = (typeof QualityFixtureName)[keyof typeof QualityFixtureName];
+export declare const AllQualityFixtureNames: readonly QualityFixtureName[];
+export declare const QualityFixtureSetName: Readonly<{
+    readonly ProjectMix: "project_mix";
+}>;
+export type QualityFixtureSetName = (typeof QualityFixtureSetName)[keyof typeof QualityFixtureSetName];
+export declare const AllQualityFixtureSetNames: readonly QualityFixtureSetName[];
+export interface QualityStringVariation {
+    value: string;
+}
+export interface QualityRatioVariation {
+    name: string;
+    inputRatio: number;
+}
+export interface QualityMetricVariation {
+    name: string;
+    value: number;
+}
+export interface QualityMetricVariations {
+    retryLoops: QualityMetricVariation[];
+    signalDensity: QualityMetricVariation[];
+    specQualityScore: QualityMetricVariation[];
+    filesTouched: QualityMetricVariation[];
+    linesChanged: QualityMetricVariation[];
+}
+export interface QualityVariations {
+    outcomes: QualityStringVariation[];
+    projects: QualityStringVariation[];
+    scopes: QualityStringVariation[];
+    taskTitles: QualityStringVariation[];
+    tokenRatios: QualityRatioVariation[];
+    metrics: QualityMetricVariations;
+}
+export interface QualitySessionFixture {
+    name: QualityFixtureName;
+    id: string;
+    date: string;
+    project: string;
+    scope: string;
+    title: string;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    turnCount: number;
+    toolCalls: number;
+    outcome: string;
+    filesTouched: number;
+    linesChanged: number;
+    durationMinutes: number;
+    retryLoops: number;
+    retryTokensWasted: number;
+    withinSessionReverts: number;
+    signalDensity: number;
+    specQualityScore: number;
+    explorationRatio: number;
+    scopeBreadth: number;
+    discoveryTurns: number;
+}
+export interface QualityFixtureSet {
+    name: QualityFixtureSetName;
+    cases: QualityFixtureName[];
+}
+export interface QualityFixtures {
+    sessions: QualitySessionFixture[];
+    sets: QualityFixtureSet[];
+    variations: QualityVariations;
+}
+export declare function loadQualityFixtures(): QualityFixtures;
+export declare function sessionByName(fixtures: QualityFixtures, name: QualityFixtureName): QualitySessionFixture | undefined;
+export declare function setByName(fixtures: QualityFixtures, name: QualityFixtureSetName): QualityFixtureSet | undefined;
+export declare function toQualitySession(fixture: QualitySessionFixture): QualitySession;
+export declare function qualitySessions(fixtures: QualityFixtures): QualitySession[];
+export declare function qualitySessionsForSet(fixtures: QualityFixtures, name: QualityFixtureSetName): QualitySession[];

package/dist/fixtures/quality.js

@@ -0,0 +1,36 @@
+import { canonicalQualityFixtures } from "../internal/generated/quality-fixtures.gen.js";
+export const QualityFixtureName = Object.freeze({
+    ResolvedTypical: "resolved_typical",
+    ResolvedHighTokens: "resolved_high_tokens",
+    PartialMedium: "partial_medium",
+    FailedComplex: "failed_complex",
+    ResolvedMinimal: "resolved_minimal",
+});
+export const AllQualityFixtureNames = Object.freeze(Object.values(QualityFixtureName));
+export const QualityFixtureSetName = Object.freeze({ ProjectMix: "project_mix" });
+export const AllQualityFixtureSetNames = Object.freeze(Object.values(QualityFixtureSetName));
+export function loadQualityFixtures() { return structuredClone(canonicalQualityFixtures); }
+export function sessionByName(fixtures, name) {
+    const fixture = fixtures.sessions.find((candidate) => candidate.name === name);
+    return fixture === undefined ? undefined : structuredClone(fixture);
+}
+export function setByName(fixtures, name) {
+    const fixture = fixtures.sets.find((candidate) => candidate.name === name);
+    return fixture === undefined ? undefined : structuredClone(fixture);
+}
+export function toQualitySession(fixture) {
+    const { name: _name, ...session } = fixture;
+    return structuredClone(session);
+}
+export function qualitySessions(fixtures) { return fixtures.sessions.map(toQualitySession); }
+export function qualitySessionsForSet(fixtures, name) {
+    const fixtureSet = setByName(fixtures, name);
+    if (fixtureSet === undefined)
+        throw new Error(`unknown quality fixture set ${JSON.stringify(name)}`);
+    return fixtureSet.cases.map((caseName) => {
+        const fixture = sessionByName(fixtures, caseName);
+        if (fixture === undefined)
+            throw new Error(`quality fixture set ${JSON.stringify(name)} references unknown case ${JSON.stringify(caseName)}`);
+        return toQualitySession(fixture);
+    });
+}

package/dist/fixtures/timeline.d.ts

@@ -0,0 +1,53 @@
+import type { CommitRef, RewrittenCommit, SessionAssociation, SessionID, TimelineSessionRef } from "../index.js";
+import type { Case } from "../testcase.js";
+export type TimelineFixtureSessionInput = Omit<TimelineSessionRef, "harness"> & {
+    harness: string;
+};
+export interface TimelineFixtureEvidenceObservation {
+    kind: string;
+    recordedCommitHash?: string;
+    touchedFilePath?: string;
+    branchName?: string;
+    windowStartMs?: number;
+    windowEndMs?: number;
+}
+export type TimelineFixtureAssociationInput = Omit<SessionAssociation, "conclusion" | "confidence" | "evidence"> & {
+    conclusion: string;
+    confidence: string;
+    evidence: TimelineFixtureEvidenceObservation[] | null;
+};
+export type TimelineFixtureCommitInput = Omit<CommitRef, "sessionIds" | "associations"> & {
+    sessionIds: SessionID[] | null;
+    associations: TimelineFixtureAssociationInput[] | null;
+};
+export type TimelineFixtureRepairKind = "set_session_binding_true" | "replace_successor_association";
+export interface TimelineFixtureSetSessionBindingRepair {
+    kind: "set_session_binding_true";
+    sessionId: SessionID;
+    postMutationValid: boolean;
+}
+export interface TimelineFixtureReplaceSuccessorAssociationRepair {
+    kind: "replace_successor_association";
+    ghostHash: string;
+    successorHash: string;
+    associationId: SessionAssociation["id"];
+    postMutationValid: boolean;
+}
+export type TimelineFixtureRepair = TimelineFixtureSetSessionBindingRepair | TimelineFixtureReplaceSuccessorAssociationRepair;
+export interface TimelineFixtureInput {
+    sessions: TimelineFixtureSessionInput[];
+    commits: TimelineFixtureCommitInput[];
+    rewrittenCommits?: RewrittenCommit[];
+}
+export interface TimelineFixtureExpected {
+    errorContains?: string;
+    repair?: TimelineFixtureRepair;
+}
+export type TimelineFixtureCase = Case<TimelineFixtureInput, TimelineFixtureExpected> & {
+    family: string;
+};
+export interface TimelineFixtureCorpus {
+    cases: TimelineFixtureCase[];
+    successorAssociationMirrorCases: TimelineFixtureCase[];
+}
+export declare function loadTimelineFixtures(): TimelineFixtureCorpus;

package/dist/fixtures/timeline.js

@@ -0,0 +1,2 @@
+import { canonicalTimelineFixtures } from "../internal/generated/timeline-fixtures.gen.js";
+export function loadTimelineFixtures() { return structuredClone(canonicalTimelineFixtures); }

package/dist/fixtures.d.ts

@@ -0,0 +1,2 @@
+export * from "./fixtures/quality.js";
+export * from "./fixtures/timeline.js";

package/dist/fixtures.js

@@ -0,0 +1,2 @@
+export * from "./fixtures/quality.js";
+export * from "./fixtures/timeline.js";

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./internal/generated/public-contract.gen.js";
+export * from "./internal/generated/enums.gen.js";
+export * from "./internal/generated/versions.gen.js";
+import { type ProjectHash } from "./internal/generated/contract/zod.gen.js";
+export declare function isProjectHash(value: unknown): value is ProjectHash;
+export declare function validateProjectHash(value: unknown): asserts value is ProjectHash;
+export declare function newProjectHash(raw: string): ProjectHash;
+export type PushContractVersion = import("./internal/generated/contract/zod.gen.js").ContractVersion;

package/dist/index.js

@@ -0,0 +1,36 @@
+export * from "./internal/generated/public-contract.gen.js";
+export * from "./internal/generated/enums.gen.js";
+export * from "./internal/generated/versions.gen.js";
+import { zProjectHash } from "./internal/generated/contract/zod.gen.js";
+function assertProjectHash(value, operation) {
+    if (!isProjectHash(value)) {
+        const rendered = renderProjectHashInput(value);
+        throw new TypeError("ProjectHash validation failed for " + rendered + " at @peasant-labs/schema ProjectHash during " + operation + ": the value is not a 64-character lowercase hexadecimal string; callers cannot use it as a canonical project identity; pass the lowercase SHA-256 hex digest of the project origin URL or local path.");
+    }
+}
+function renderProjectHashInput(value) {
+    try {
+        const json = JSON.stringify(value);
+        if (json !== undefined)
+            return json;
+    }
+    catch {
+        // Fall through to String for values whose JSON hooks throw.
+    }
+    try {
+        return String(value);
+    }
+    catch {
+        return "<unrenderable value>";
+    }
+}
+export function isProjectHash(value) {
+    return zProjectHash.safeParse(value).success;
+}
+export function validateProjectHash(value) {
+    assertProjectHash(value, "validateProjectHash");
+}
+export function newProjectHash(raw) {
+    assertProjectHash(raw, "newProjectHash");
+    return raw;
+}