@peasant-labs/schema 0.29.1 → 0.31.0

package/dist/collective-status.d.ts

@@ -0,0 +1 @@
+export declare function collectiveFetchHTTPStatus(value: unknown): number;

package/dist/collective-status.js

@@ -0,0 +1,35 @@
+import { zCollectiveFetchReport } from "./internal/generated/contract/zod.gen.js";
+// Keep the public raw boundary above the generated parser, not inside its
+// refinement module: Zod -> pure semantics, public status -> complete Zod.
+// No partial parallel validator or runtime import cycle is needed.
+export function collectiveFetchHTTPStatus(value) {
+    try {
+        const parsed = zCollectiveFetchReport.safeParse(value);
+        if (!parsed.success)
+            return 500;
+        const report = parsed.data;
+        if (report.outcome === "complete")
+            return 200;
+        const issues = [...report.issues];
+        let cancelled = false;
+        for (const domain of report.domains) {
+            cancelled ||= domain.state === "cancelled";
+            if (domain.issue != null)
+                issues.push(domain.issue);
+            for (const source of domain.sourceOutcomes)
+                if (source.issue != null)
+                    issues.push(source.issue);
+            for (const scope of domain.associations?.scopes ?? []) {
+                cancelled ||= scope.state === "cancelled";
+                if (scope.issue != null)
+                    issues.push(scope.issue);
+            }
+        }
+        const ranks = { persistence: 5, auth: 4, deadline: 3, remote: 2, contract: 2, superseded: 1 };
+        const rank = issues.reduce((highest, issue) => Math.max(highest, ranks[issue.code]), cancelled ? 3 : 0);
+        return [500, 409, 502, 504, 401, 500][rank] ?? 500;
+    }
+    catch {
+        return 500;
+    }
+}

package/dist/collective-validation.d.ts

@@ -0,0 +1,19 @@
+import type { CollectiveObservationScope, LocalContributionEvidenceKind } from "./internal/generated/contract/zod.gen.js";
+export interface ContributionTraversalIdentity {
+    scope: CollectiveObservationScope;
+    incarnation: string;
+    kind: LocalContributionEvidenceKind;
+    generation: string;
+}
+export interface LocalContributionHistoryQuery {
+    kind: LocalContributionEvidenceKind;
+    collectiveId?: string;
+    page: number;
+    limit: number;
+    revision?: string;
+}
+export declare function validateContributionHistoryQuery(query: LocalContributionHistoryQuery, current: string): number;
+export declare function normalizeCollectiveObservationScope(raw: string, userId: string): CollectiveObservationScope;
+export declare function encodeContributionTraversalRevision(value: ContributionTraversalIdentity): string;
+export declare function parseContributionTraversalRevision(token: string): ContributionTraversalIdentity;
+export declare function collectiveContractIssue(name: string, value: unknown): string | undefined;

package/dist/collective-validation.js

@@ -0,0 +1,252 @@
+export function validateContributionHistoryQuery(query, current) {
+    if (!kinds.includes(query.kind) || !Number.isSafeInteger(query.page) || query.page < 1 || !Number.isSafeInteger(query.limit) || query.limit < 1 || query.limit > 200 || (query.collectiveId !== undefined && !uuid.test(query.collectiveId)))
+        return 400;
+    if (query.revision === undefined)
+        return query.page > 1 ? 400 : 200;
+    try {
+        parseContributionTraversalRevision(query.revision);
+    }
+    catch {
+        return 400;
+    }
+    return query.revision === current ? 200 : 409;
+}
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const kinds = ["remote-attempts", "receipts", "operation-diagnostics"];
+const decimal = (v) => /^(0|[1-9][0-9]{0,19})$/.test(v) && BigInt(v) <= 18446744073709551615n;
+const utc = (v) => v == null || (!/^0001-01-01T00:00:00(?:\.0+)?Z$/.test(v) && v.endsWith("Z"));
+function invalid(reason) { return new TypeError(`Collective observation contract validation failed during metadata processing: ${reason}; retain prior evidence and correct the request or fetch validated metadata before retrying.`); }
+export function normalizeCollectiveObservationScope(raw, userId) {
+    if (/[^\x21-\x7e]/.test(raw))
+        throw invalid("scope URL requires printable ASCII and explicit ASCII IDNA host spelling");
+    if (new TextEncoder().encode(raw).length > 1024 || !uuid.test(userId) || raw.includes("\\") || raw.trim() !== raw)
+        throw invalid("scope URL or account identity is invalid");
+    const parts = /^([A-Za-z][A-Za-z0-9+.-]*):\/\/([^/?#]*)([^?#]*)(?:\?[^#]*)?(?:#.*)?$/.exec(raw);
+    if (parts === null || /[\t\r\n]/.test(raw))
+        throw invalid("scope requires the supported absolute URL grammar");
+    const authority = parts[2].slice(parts[2].lastIndexOf("@") + 1), rawPath = parts[3];
+    if (authority.endsWith(":") || rawPath.includes("//") || !/^[A-Za-z0-9/._~!$&'()*+,;=:@-]*$/.test(rawPath))
+        throw invalid("scope explicit port or unescaped base path is invalid");
+    const hostPort = /^(\[[0-9A-Fa-f:.]+\]|[^:]+)(?::([0-9]+))?$/.exec(authority);
+    if (hostPort === null)
+        throw invalid("scope host/port grammar is invalid");
+    const rawHost = hostPort[1].toLowerCase(), port = hostPort[2];
+    if (port !== undefined && (port.length > 5 || Number(port) < 1 || Number(port) > 65535))
+        throw invalid("scope port is outside 1..65535 or exceeds five digits");
+    if (!rawHost.startsWith("[")) {
+        const name = rawHost.replace(/\.$/, ""), labels = name.split(".");
+        if (name.length === 0 || name.length > 253)
+            throw invalid("scope DNS name is invalid");
+        if (/^(?:[0-9]+|0x[0-9a-f]*)$/.test(labels.at(-1))) {
+            if (labels.length !== 4 || rawHost !== name || labels.some(label => !/^(0|[1-9][0-9]*)$/.test(label) || Number(label) > 255))
+                throw invalid("ambiguous numeric IPv4 spelling is unsupported; use four decimal components");
+        }
+        else if (labels.some(label => label.length > 63 || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label)))
+            throw invalid("scope requires ASCII DNS labels");
+    }
+    const scheme = parts[1].toLowerCase();
+    if (scheme !== "http" && scheme !== "https")
+        throw invalid("scope protocol is unsupported");
+    let host = rawHost;
+    if (rawHost.startsWith("[")) {
+        try {
+            host = new URL(scheme + "://" + authority).hostname;
+        }
+        catch {
+            throw invalid("scope IPv6 literal is invalid");
+        }
+    }
+    let normalizedPort = port === undefined ? "" : String(Number(port));
+    if ((scheme === "https" && normalizedPort === "443") || (scheme === "http" && normalizedPort === "80"))
+        normalizedPort = "";
+    const segments = [];
+    for (const segment of rawPath.split("/")) {
+        if (segment === "..")
+            segments.pop();
+        else if (segment !== "" && segment !== ".")
+            segments.push(segment);
+    }
+    return { villageUrl: scheme + "://" + host + (normalizedPort === "" ? "" : ":" + normalizedPort) + (segments.length === 0 ? "" : "/" + segments.join("/")), userId };
+}
+function scopeValid(scope) { try {
+    const v = normalizeCollectiveObservationScope(scope.villageUrl, scope.userId);
+    return v.villageUrl === scope.villageUrl && v.userId === scope.userId;
+}
+catch {
+    return false;
+} }
+export function encodeContributionTraversalRevision(value) {
+    if (!scopeValid(value.scope) || !uuid.test(value.incarnation) || !kinds.includes(value.kind) || !decimal(value.generation))
+        throw invalid("traversal identity fields are invalid");
+    const json = JSON.stringify(["1", value.scope.villageUrl, value.scope.userId, value.incarnation, value.kind, value.generation]);
+    const token = btoa(String.fromCharCode(...new TextEncoder().encode(json))).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+    if (token.length > 4096)
+        throw invalid("traversal token exceeds its byte bound");
+    return token;
+}
+export function parseContributionTraversalRevision(token) {
+    if (token.length === 0 || token.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(token))
+        throw invalid("traversal token is missing or not bounded base64url");
+    let fields;
+    try {
+        fields = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(atob(token.replaceAll("-", "+").replaceAll("_", "/")), c => c.charCodeAt(0))));
+    }
+    catch {
+        throw invalid("traversal token framing is invalid");
+    }
+    if (!Array.isArray(fields) || fields.length !== 6 || fields.some(v => typeof v !== "string") || fields[0] !== "1")
+        throw invalid("traversal token version or field framing is invalid");
+    const value = { scope: { villageUrl: fields[1], userId: fields[2] }, incarnation: fields[3], kind: fields[4], generation: fields[5] };
+    if (encodeContributionTraversalRevision(value) !== token)
+        throw invalid("traversal token is not canonical");
+    return value;
+}
+// Called only after the generated Zod shape parser succeeds. This function
+// supplies cross-field semantics; it does not replace generated wire parsing.
+export function collectiveContractIssue(name, value) {
+    if (name === "VillageContributedCollectivesResponse") {
+        const v = value;
+        if (new Set(v.collectives.map(c => c.id)).size !== v.collectives.length)
+            return "contribution discovery repeats a collective identity";
+        return;
+    }
+    if (name === "VillageOrganizationCollectivesResponse") {
+        const v = value;
+        if (new Set(v.collectives.map(c => c.id)).size !== v.collectives.length)
+            return "organization projection repeats a collective identity";
+        return;
+    }
+    if (name === "CollectiveObservationScope")
+        return scopeValid(value) ? undefined : "scope is not normalized";
+    if (name === "ContributionTraversalRevision") {
+        try {
+            parseContributionTraversalRevision(value);
+            return;
+        }
+        catch {
+            return "traversal token is malformed";
+        }
+    }
+    if (name === "OperationIssue") {
+        const v = value;
+        if (!v.message.trim() || !v.retry.trim() || new TextEncoder().encode(v.message).length > 2048 || new TextEncoder().encode(v.retry).length > 2048)
+            return "issue needs bounded actionable message/retry";
+        return;
+    }
+    if (name === "PullAssociationMetadataResult") {
+        const v = value, needsTime = v.state !== "unknown", needsWarning = v.state === "stale" || v.state === "unknown";
+        if ((v.observedAt != null) !== needsTime || !utc(v.observedAt) || (v.warning != null) !== needsWarning || (v.warning != null && v.warning.operation !== "pull"))
+            return "metadata state/time/warning pairing is invalid";
+        return;
+    }
+    if (name === "LocalConfirmedContributionReceipt") {
+        const v = value;
+        if (new TextEncoder().encode(v.receiptId).length > 256 || (v.sourceReceiptId != null && new TextEncoder().encode(v.sourceReceiptId).length > 256))
+            return "receipt identities exceed their encoded byte bounds";
+        if (!utc(v.confirmedAt) || (v.sourceReceiptId != null && v.sourceReceiptId === "") || (v.operation === "publish" ? v.outcome !== "published" : v.operation !== "share" || v.outcome !== "submitted"))
+            return "receipt must confirm its actual publish/share effect and optional known target";
+        return;
+    }
+    if (name === "LocalOperationDiagnostic") {
+        const v = value;
+        if (!utc(v.attemptedAt) || v.operation !== v.issue.operation)
+            return "diagnostic time/issue operation mismatch";
+        return;
+    }
+    if (name === "CollectiveObservation") {
+        const v = value;
+        if (!utc(v.observedAt) || new Set(v.reasons).size !== v.reasons.length)
+            return "observation requires UTC time and unique reasons";
+        return;
+    }
+    if (name === "CollectiveFetchDomainSummary") {
+        const v = value;
+        if (![v.lastAttemptAt, v.lastCompletedAt].every(utc) || (v.lastInstalledRevision != null && !decimal(v.lastInstalledRevision)))
+            return "summary dates/revision are invalid";
+        return;
+    }
+    if (name === "CollectiveFetchDomainResult")
+        return domainIssue(value);
+    if (name === "CollectiveFetchReport") {
+        const v = value;
+        if (!decimal(v.cacheRevision) || new Set(v.domains.map(d => d.domain)).size !== 3)
+            return "report requires all independent domains and decimal revision";
+        const requested = v.domains.filter(d => d.requested), complete = requested.filter(d => d.state === "complete").length;
+        const progress = requested.some(d => d.state === "complete" || d.commit !== "retained");
+        const outcome = requested.length > 0 && complete === requested.length ? "complete" : progress ? "partial" : "failed";
+        if (v.outcome !== outcome || (outcome === "complete" && v.issues.length !== 0))
+            return "overall outcome disagrees with independently completed effects";
+        return;
+    }
+    if (name === "CollectiveObservationResponse") {
+        const v = value;
+        if (!decimal(v.cacheRevision) || new Set(v.collectives.map(c => c.id)).size !== v.collectives.length || (v.fetch.latestReport != null && (v.fetch.latestReport.scope.villageUrl !== v.scope.villageUrl || v.fetch.latestReport.scope.userId !== v.scope.userId)))
+            return "catalog revision/identity or latest report scope mismatch";
+        return;
+    }
+    if (name === "CollectiveFetchSummary") {
+        const v = value;
+        if (!utc(v.lastCompletedFetchAt) || !utc(v.lastAttemptAt))
+            return "fetch summary dates must be UTC observations";
+        return;
+    }
+    if (name === "LocalContributionHistoryResponse") {
+        const v = value;
+        let identity;
+        try {
+            identity = parseContributionTraversalRevision(v.traversalRevision);
+        }
+        catch {
+            return "history token is malformed";
+        }
+        if (identity.scope.villageUrl !== v.scope.villageUrl || identity.scope.userId !== v.scope.userId || identity.kind !== v.kind)
+            return "history token scope/kind mismatch";
+        const rows = v.kind === "remote-attempts" ? v.remoteAttempts : v.kind === "receipts" ? v.receipts : v.operationDiagnostics;
+        if (rows.length > v.limit || rows.length > v.total)
+            return "history rows exceed page limit or filtered total";
+        return;
+    }
+}
+function domainIssue(v) {
+    if (v.requested === (v.state === "not_requested") || ![v.startedAt, v.lastAttemptAt, v.completedAt, v.lastCompletedAt].every(utc) || (v.lastInstalledRevision != null && !decimal(v.lastInstalledRevision)))
+        return "domain requested/state, dates or revision mismatch";
+    if (v.state === "complete") {
+        if (v.completedAt == null || v.lastCompletedAt == null || v.lastInstalledRevision == null || v.commit === "retained" || v.issue != null)
+            return "complete domain needs installed completion evidence";
+    }
+    else if (v.completedAt != null || (v.domain !== "associations" && v.commit !== "retained") || (v.state !== "not_requested" && v.issue == null))
+        return "incomplete domain must retain its previous complete dataset with an issue";
+    for (const s of v.sourceOutcomes)
+        if ((v.state === "complete" && !s.complete) || !utc(s.observedAt) || (s.outcome === "failed") === s.complete || (s.complete && s.observedAt == null) || ((s.outcome === "failed") !== (s.issue != null)))
+            return "source completeness/time/issue mismatch";
+    if (v.domain !== "associations" && v.associations != null)
+        return "association scopes belong only to associations";
+    if (v.domain === "associations" && v.requested && v.associations == null)
+        return "requested associations require scoped results";
+    if (!v.requested && (v.commit !== "retained" || v.issue != null || v.sourceOutcomes.length !== 0 || v.associations != null))
+        return "not-requested domain cannot claim effects/issues";
+    if (v.associations != null) {
+        const a = v.associations;
+        if (a.scopes.length !== a.requested || a.completed + a.failed !== a.requested || new Set(a.scopes.map(s => s.transcriptId)).size !== a.scopes.length)
+            return "association counts or identities disagree";
+        let n = 0;
+        for (const s of a.scopes) {
+            if (s.state === "not_requested" || !utc(s.observedAt) || !utc(s.completedAt))
+                return "association state/date invalid";
+            if (s.state === "complete") {
+                n++;
+                if (s.completedAt == null || s.observedAt == null || s.commit === "retained" || s.issue != null)
+                    return "completed association set needs actual committed observation";
+            }
+            else if (s.issue == null || s.commit !== "retained" || s.completedAt != null)
+                return "incomplete association set must retain prior evidence";
+        }
+        if (n !== a.completed || (v.state === "complete" && a.failed !== 0))
+            return "association completion count disagrees";
+        const commit = a.scopes.some(s => s.commit === "updated") ? "updated" : n > 0 ? "unchanged" : "retained";
+        if (commit === "updated" && v.commit !== "updated")
+            return "updated association scope requires updated aggregate effect";
+        if (v.state !== "complete" && v.commit !== commit)
+            return "partial association domain lost actual committed effects";
+    }
+}

package/dist/contribution-attempt.d.ts

@@ -0,0 +1,7 @@
+import { type LocalRemoteContributionAttempt, type VillageShareEventActor, type VillageShareStatus } from "./internal/generated/contract/zod.gen.js";
+export type VillageContributionAttemptReconciliation = "inserted" | "unchanged" | "updated" | "superseded";
+export declare function villageContributionAttemptActor(status: VillageShareStatus): VillageShareEventActor;
+export declare function reconcileVillageContributionAttempt(saved: LocalRemoteContributionAttempt | undefined, incoming: LocalRemoteContributionAttempt): {
+    attempt: LocalRemoteContributionAttempt;
+    disposition: VillageContributionAttemptReconciliation;
+};

package/dist/contribution-attempt.js

@@ -0,0 +1,47 @@
+import { zLocalRemoteContributionAttempt, } from "./internal/generated/contract/zod.gen.js";
+// Capacity is not a moderator UUID or proof of a manual decision.
+export function villageContributionAttemptActor(status) {
+    switch (status) {
+        case "pending": return "";
+        case "approved":
+        case "rejected": return "moderator";
+        case "retracted": return "owner";
+        case "revoked": return "collective";
+        default: throw conflict("status is outside the share-attempt menu");
+    }
+}
+// Select the verified storage scope before calling, and reconcile under the
+// write transaction against latest evidence. Different ordinals are distinct
+// rows; pass undefined saved evidence for a previously unseen identity.
+export function reconcileVillageContributionAttempt(saved, incoming) {
+    const next = zLocalRemoteContributionAttempt.parse(incoming);
+    if (saved === undefined)
+        return { attempt: next, disposition: "inserted" };
+    const old = zLocalRemoteContributionAttempt.parse(saved);
+    if (old.collectiveId !== next.collectiveId || old.transcriptId !== next.transcriptId || old.attempt.event_num !== next.attempt.event_num) {
+        throw conflict("the incoming attempt has a different collective, transcript, or ordinal identity");
+    }
+    if (!equalTime(old.attempt.recorded_at, next.attempt.recorded_at))
+        throw conflict("recorded_at changed for an existing attempt identity");
+    if (old.attempt.status === next.attempt.status && old.attempt.decided_by_actor === next.attempt.decided_by_actor && equalTime(old.attempt.decided_at, next.attempt.decided_at)) {
+        return { attempt: old, disposition: "unchanged" };
+    }
+    if (old.attempt.status === "pending") {
+        if (next.attempt.decided_at === null)
+            throw conflict("an in-place pending decision requires a newly recorded decided_at");
+        next.firstSeenAt = old.firstSeenAt;
+        return { attempt: next, disposition: "updated" };
+    }
+    if (next.attempt.status === "pending")
+        return { attempt: old, disposition: "superseded" };
+    throw conflict("terminal status or decision evidence changed for an existing attempt identity");
+}
+// Do not use Date.parse: millisecond rounding would erase terminal timestamp
+// conflicts present in the Go nanosecond contract. Zod has validated UTC form.
+function equalTime(left, right) {
+    const canonical = (value) => value === null ? null : value.replace(/\.([0-9]*?)0+Z$/, (_match, fraction) => fraction === "" ? "Z" : `.${fraction}Z`);
+    return canonical(left) === canonical(right);
+}
+function conflict(reason) {
+    return new TypeError(`Collective contribution attempt reconciliation failed at @peasant-labs/schema during history validation: ${reason}; retain prior evidence without installing this observation and fetch validated owner history before retrying.`);
+}

package/dist/fixtures/session-graph.d.ts

@@ -2078,7 +2078,7 @@ export declare function sessionGraphFixtures(): {
     };
     readonly authoritative_required_names: readonly ["authoritative-entry-label", "authoritative-entry-navigation", "authoritative-entry-explanation"];
     readonly typescriptConstraints: {
-        readonly countCarriers: readonly ["AuthoritativeSessionStats", "LocalSyncSummary", "SessionStats", "SessionSummary", "SessionDetailPayload", "SessionDetailReadPayload", "VillageContributableTranscript", "VillageGroupTranscript", "VillagePendingShare", "VillageTranscript", "VillageUserGroupShare"];
+        readonly countCarriers: readonly ["AuthoritativeSessionStats", "LocalSyncSummary", "SessionStats", "SessionSummary", "SessionDetailPayload", "SessionDetailReadPayload", "VillageContributableTranscript", "VillageCollectiveTranscript", "VillagePendingShare", "VillageTranscript", "VillageUserCollectiveShare"];
         readonly strictObjects: {
             readonly PublicSourceAnchor: {
                 readonly kind: "general_source_session";
@@ -4692,7 +4692,7 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "eleven released base fields do not fabricate unavailable prompts settings";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroupDetailRecord";
+                    readonly schema: "VillageCollectiveDetailRecord";
                     readonly payload: {
                         readonly id: "123e4567-e89b-12d3-a456-426614174001";
                         readonly name: "collective";
@@ -4721,7 +4721,7 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "explicit false is a supplied fact and must remain present";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroupDetailRecord";
+                    readonly schema: "VillageCollectiveDetailRecord";
                     readonly payload: {
                         readonly id: "123e4567-e89b-12d3-a456-426614174001";
                         readonly name: "collective";
@@ -4752,7 +4752,7 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "source-backed true setting remains present";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroupDetailRecord";
+                    readonly schema: "VillageCollectiveDetailRecord";
                     readonly payload: {
                         readonly id: "123e4567-e89b-12d3-a456-426614174001";
                         readonly name: "collective";
@@ -4783,7 +4783,7 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "optional present mode still uses the closed menu";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroupDetailRecord";
+                    readonly schema: "VillageCollectiveDetailRecord";
                     readonly payload: {
                         readonly id: "123e4567-e89b-12d3-a456-426614174001";
                         readonly name: "collective";
@@ -4813,7 +4813,7 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "independent canonical prompts contract remains required, not weakened by read compatibility";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroup";
+                    readonly schema: "VillageCollective";
                     readonly payload: {
                         readonly id: "123e4567-e89b-12d3-a456-426614174001";
                         readonly name: "collective";
@@ -4842,7 +4842,7 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "canonical group still accepts its supplied prompts configuration";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroup";
+                    readonly schema: "VillageCollective";
                     readonly payload: {
                         readonly id: "123e4567-e89b-12d3-a456-426614174001";
                         readonly name: "collective";
@@ -5223,8 +5223,8 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "omitted-view GET detail preserves the eleven group fields without invented prompts settings";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroupDetailResponse";
-                    readonly route: "/api/v1/groups/{id}";
+                    readonly schema: "VillageCollectiveDetailResponse";
+                    readonly route: "/api/v1/collectives/{id}";
                     readonly payload: {
                         readonly group: {
                             readonly id: "123e4567-e89b-12d3-a456-426614174001";
@@ -5269,8 +5269,8 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "grouped GET detail preserves identical base group values and omitted settings";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroupedGroupDetailResponse";
-                    readonly route: "/api/v1/groups/{id}";
+                    readonly schema: "VillageGroupedCollectiveDetailResponse";
+                    readonly route: "/api/v1/collectives/{id}";
                     readonly payload: {
                         readonly group: {
                             readonly id: "123e4567-e89b-12d3-a456-426614174001";
@@ -5322,8 +5322,8 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "flat GET detail retains source-backed false and informational mode";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroupDetailResponse";
-                    readonly route: "/api/v1/groups/{id}";
+                    readonly schema: "VillageCollectiveDetailResponse";
+                    readonly route: "/api/v1/collectives/{id}";
                     readonly payload: {
                         readonly group: {
                             readonly id: "123e4567-e89b-12d3-a456-426614174001";
@@ -5370,8 +5370,8 @@ export declare function sessionGraphFixtures(): {
                     readonly description: "grouped GET detail retains the same explicit false settings as flat reads";
                 };
                 readonly input: {
-                    readonly schema: "VillageGroupedGroupDetailResponse";
-                    readonly route: "/api/v1/groups/{id}";
+                    readonly schema: "VillageGroupedCollectiveDetailResponse";
+                    readonly route: "/api/v1/collectives/{id}";
                     readonly payload: {
                         readonly group: {
                             readonly id: "123e4567-e89b-12d3-a456-426614174001";

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export * from "./internal/generated/public-contract.gen.js";
 export * from "./internal/generated/enums.gen.js";
+export * from "./internal/generated/collective-compatibility.gen.js";
 export * from "./internal/generated/redaction-categories.gen.js";
 export * from "./internal/generated/content-capabilities.gen.js";
 export * from "./internal/generated/versions.gen.js";
+export { reconcileVillageContributionAttempt, villageContributionAttemptActor, type VillageContributionAttemptReconciliation } from "./contribution-attempt.js";
+export { normalizeCollectiveObservationScope, encodeContributionTraversalRevision, parseContributionTraversalRevision, validateContributionHistoryQuery, type ContributionTraversalIdentity, type LocalContributionHistoryQuery } from "./collective-validation.js";
+export { collectiveFetchHTTPStatus } from "./collective-status.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;

package/dist/index.js

@@ -1,8 +1,12 @@
 export * from "./internal/generated/public-contract.gen.js";
 export * from "./internal/generated/enums.gen.js";
+export * from "./internal/generated/collective-compatibility.gen.js";
 export * from "./internal/generated/redaction-categories.gen.js";
 export * from "./internal/generated/content-capabilities.gen.js";
 export * from "./internal/generated/versions.gen.js";
+export { reconcileVillageContributionAttempt, villageContributionAttemptActor } from "./contribution-attempt.js";
+export { normalizeCollectiveObservationScope, encodeContributionTraversalRevision, parseContributionTraversalRevision, validateContributionHistoryQuery } from "./collective-validation.js";
+export { collectiveFetchHTTPStatus } from "./collective-status.js";
 import { requiredContentCapabilities, KnownContentCapability } from "./internal/generated/content-capabilities.gen.js";
 import { zNativeMetadataRecord, zTurnDetail, zProjectHash, zServerMessage, zSessionDetailPayload, zSessionDetailReadPayload, zTranscriptContent } from "./internal/generated/contract/zod.gen.js";
 import { maxNativeMetadataStringBytes } from "./internal/generated/metadata-limits.gen.js";

package/dist/internal/generated/collective-compatibility.gen.d.ts

@@ -0,0 +1,116 @@
+/** @deprecated Use zVillageAssignableCollectiveRole; retained for the complete alias release window. */
+export { zVillageAssignableCollectiveRole as zVillageAssignableGroupRole } from "./contract/zod.gen.js";
+/** @deprecated Use VillageAssignableCollectiveRole; retained for the complete alias release window. */
+export { VillageAssignableCollectiveRole as VillageAssignableGroupRole } from "./enums.gen.js";
+/** @deprecated Use AllVillageAssignableCollectiveRoles; retained for the complete alias release window. */
+export { AllVillageAssignableCollectiveRoles as AllVillageAssignableGroupRoles } from "./enums.gen.js";
+/** @deprecated Use isVillageAssignableCollectiveRole; retained for the complete alias release window. */
+export { isVillageAssignableCollectiveRole as isVillageAssignableGroupRole } from "./enums.gen.js";
+/** @deprecated Use zVillageCreateCollectiveRequest; retained for the complete alias release window. */
+export { zVillageCreateCollectiveRequest as zVillageCreateGroupRequest } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCreateCollectiveRequest; retained for the complete alias release window. */
+export type { VillageCreateCollectiveRequest as VillageCreateGroupRequest } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollective; retained for the complete alias release window. */
+export { zVillageCollective as zVillageGroup } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollective; retained for the complete alias release window. */
+export type { VillageCollective as VillageGroup } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveAcceptanceMode; retained for the complete alias release window. */
+export { zVillageCollectiveAcceptanceMode as zVillageGroupAcceptanceMode } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveAcceptanceMode; retained for the complete alias release window. */
+export { VillageCollectiveAcceptanceMode as VillageGroupAcceptanceMode } from "./enums.gen.js";
+/** @deprecated Use AllVillageCollectiveAcceptanceModes; retained for the complete alias release window. */
+export { AllVillageCollectiveAcceptanceModes as AllVillageGroupAcceptanceModes } from "./enums.gen.js";
+/** @deprecated Use isVillageCollectiveAcceptanceMode; retained for the complete alias release window. */
+export { isVillageCollectiveAcceptanceMode as isVillageGroupAcceptanceMode } from "./enums.gen.js";
+/** @deprecated Use zVillageCollectiveContributor; retained for the complete alias release window. */
+export { zVillageCollectiveContributor as zVillageGroupContributor } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveContributor; retained for the complete alias release window. */
+export type { VillageCollectiveContributor as VillageGroupContributor } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveDataAccess; retained for the complete alias release window. */
+export { zVillageCollectiveDataAccess as zVillageGroupDataAccess } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveDataAccess; retained for the complete alias release window. */
+export { VillageCollectiveDataAccess as VillageGroupDataAccess } from "./enums.gen.js";
+/** @deprecated Use AllVillageCollectiveDataAccessPolicies; retained for the complete alias release window. */
+export { AllVillageCollectiveDataAccessPolicies as AllVillageGroupDataAccessPolicies } from "./enums.gen.js";
+/** @deprecated Use isVillageCollectiveDataAccess; retained for the complete alias release window. */
+export { isVillageCollectiveDataAccess as isVillageGroupDataAccess } from "./enums.gen.js";
+/** @deprecated Use zVillageCollectiveDetailRecord; retained for the complete alias release window. */
+export { zVillageCollectiveDetailRecord as zVillageGroupDetailRecord } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveDetailRecord; retained for the complete alias release window. */
+export type { VillageCollectiveDetailRecord as VillageGroupDetailRecord } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveDetailResponse; retained for the complete alias release window. */
+export { zVillageCollectiveDetailResponse as zVillageGroupDetailResponse } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveDetailResponse; retained for the complete alias release window. */
+export type { VillageCollectiveDetailResponse as VillageGroupDetailResponse } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageGroupedCollectiveDetailResponse; retained for the complete alias release window. */
+export { zVillageGroupedCollectiveDetailResponse as zVillageGroupedGroupDetailResponse } from "./contract/zod.gen.js";
+/** @deprecated Use VillageGroupedCollectiveDetailResponse; retained for the complete alias release window. */
+export type { VillageGroupedCollectiveDetailResponse as VillageGroupedGroupDetailResponse } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveMember; retained for the complete alias release window. */
+export { zVillageCollectiveMember as zVillageGroupMember } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveMember; retained for the complete alias release window. */
+export type { VillageCollectiveMember as VillageGroupMember } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveMemberRoleRequest; retained for the complete alias release window. */
+export { zVillageCollectiveMemberRoleRequest as zVillageGroupMemberRoleRequest } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveMemberRoleRequest; retained for the complete alias release window. */
+export type { VillageCollectiveMemberRoleRequest as VillageGroupMemberRoleRequest } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveMemberUsernameRequest; retained for the complete alias release window. */
+export { zVillageCollectiveMemberUsernameRequest as zVillageGroupMemberUsernameRequest } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveMemberUsernameRequest; retained for the complete alias release window. */
+export type { VillageCollectiveMemberUsernameRequest as VillageGroupMemberUsernameRequest } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveModelBreakdown; retained for the complete alias release window. */
+export { zVillageCollectiveModelBreakdown as zVillageGroupModelBreakdown } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveModelBreakdown; retained for the complete alias release window. */
+export type { VillageCollectiveModelBreakdown as VillageGroupModelBreakdown } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveRole; retained for the complete alias release window. */
+export { zVillageCollectiveRole as zVillageGroupRole } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveRole; retained for the complete alias release window. */
+export { VillageCollectiveRole as VillageGroupRole } from "./enums.gen.js";
+/** @deprecated Use AllVillageCollectiveRoles; retained for the complete alias release window. */
+export { AllVillageCollectiveRoles as AllVillageGroupRoles } from "./enums.gen.js";
+/** @deprecated Use isVillageCollectiveRole; retained for the complete alias release window. */
+export { isVillageCollectiveRole as isVillageGroupRole } from "./enums.gen.js";
+/** @deprecated Use zVillageCollectiveStatusRoleResponse; retained for the complete alias release window. */
+export { zVillageCollectiveStatusRoleResponse as zVillageGroupStatusRoleResponse } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveStatusRoleResponse; retained for the complete alias release window. */
+export type { VillageCollectiveStatusRoleResponse as VillageGroupStatusRoleResponse } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveTranscript; retained for the complete alias release window. */
+export { zVillageCollectiveTranscript as zVillageGroupTranscript } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveTranscript; retained for the complete alias release window. */
+export type { VillageCollectiveTranscript as VillageGroupTranscript } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveTranscriptStats; retained for the complete alias release window. */
+export { zVillageCollectiveTranscriptStats as zVillageGroupTranscriptStats } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveTranscriptStats; retained for the complete alias release window. */
+export type { VillageCollectiveTranscriptStats as VillageGroupTranscriptStats } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageCollectiveViewerRole; retained for the complete alias release window. */
+export { zVillageCollectiveViewerRole as zVillageGroupViewerRole } from "./contract/zod.gen.js";
+/** @deprecated Use VillageCollectiveViewerRole; retained for the complete alias release window. */
+export { VillageCollectiveViewerRole as VillageGroupViewerRole } from "./enums.gen.js";
+/** @deprecated Use AllVillageCollectiveViewerRoles; retained for the complete alias release window. */
+export { AllVillageCollectiveViewerRoles as AllVillageGroupViewerRoles } from "./enums.gen.js";
+/** @deprecated Use isVillageCollectiveViewerRole; retained for the complete alias release window. */
+export { isVillageCollectiveViewerRole as isVillageGroupViewerRole } from "./enums.gen.js";
+/** @deprecated Use zVillagePublicCollective; retained for the complete alias release window. */
+export { zVillagePublicCollective as zVillagePublicGroup } from "./contract/zod.gen.js";
+/** @deprecated Use VillagePublicCollective; retained for the complete alias release window. */
+export type { VillagePublicCollective as VillagePublicGroup } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageRemoveCollectiveMemberResponse; retained for the complete alias release window. */
+export { zVillageRemoveCollectiveMemberResponse as zVillageRemoveGroupMemberResponse } from "./contract/zod.gen.js";
+/** @deprecated Use VillageRemoveCollectiveMemberResponse; retained for the complete alias release window. */
+export type { VillageRemoveCollectiveMemberResponse as VillageRemoveGroupMemberResponse } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageUpdateCollectiveRequest; retained for the complete alias release window. */
+export { zVillageUpdateCollectiveRequest as zVillageUpdateGroupRequest } from "./contract/zod.gen.js";
+/** @deprecated Use VillageUpdateCollectiveRequest; retained for the complete alias release window. */
+export type { VillageUpdateCollectiveRequest as VillageUpdateGroupRequest } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageUserCollective; retained for the complete alias release window. */
+export { zVillageUserCollective as zVillageUserGroup } from "./contract/zod.gen.js";
+/** @deprecated Use VillageUserCollective; retained for the complete alias release window. */
+export type { VillageUserCollective as VillageUserGroup } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageUserCollectiveShare; retained for the complete alias release window. */
+export { zVillageUserCollectiveShare as zVillageUserGroupShare } from "./contract/zod.gen.js";
+/** @deprecated Use VillageUserCollectiveShare; retained for the complete alias release window. */
+export type { VillageUserCollectiveShare as VillageUserGroupShare } from "./contract/zod.gen.js";
+/** @deprecated Use zVillageVisibleCollective; retained for the complete alias release window. */
+export { zVillageVisibleCollective as zVillageVisibleGroup } from "./contract/zod.gen.js";
+/** @deprecated Use VillageVisibleCollective; retained for the complete alias release window. */
+export type { VillageVisibleCollective as VillageVisibleGroup } from "./contract/zod.gen.js";