@mdbase-dev/pickle 0.1.0-beta.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdbase connect contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# `@mdbase-dev/pickle`
+
+Contract adapter and provisioning resources for Pickle collections.
+
+```ts
+const pickle = new PickleCollection(connect);
+const requests = await pickle.list();
+await pickle.respond(requests[0], {
+  decision: "approve",
+  comment: "Looks right."
+});
+```
+
+The adapter uses ordinary mdbase operations. Request state is derived from
+linked response records, and no record payload is stored outside the collection.
+
+For an inbox, use `pickle.list({ includeBody: false })`. It still waits for all
+response links before deriving pending, answered, and conflict states, but does
+not transfer every request's Markdown context. Fetch an opened request's context
+with `await pickle.readBody(request, { signal, timeoutMs: 10_000 })`. Response
+bodies are never needed for lifecycle calculation and are omitted from queries.
+
+Pickle requests 256 records per page from the first query. Cursor authorities
+pin that initial size; continuation requests reuse the cursor rather than asking
+for an ineffective larger limit.

package/dist/index.d.ts

@@ -0,0 +1,134 @@
+import { type CollectionContractDescriptor, type CollectionDescription, type CollectionTypeDescriptor, type JsonObject, type RecordDocument, type ConnectRequestOptions, type MdbaseConnection, type PendingMutation } from "@mdbase-dev/connect";
+export { PICKLE_ACK_RESPONSE_TYPE_DOCUMENT, PICKLE_ATTACHMENT_TYPE_DOCUMENT, PICKLE_APPROVAL_RESPONSE_TYPE_DOCUMENT, PICKLE_REQUEST_CONTRACT_DOCUMENT, PICKLE_REQUEST_CONTRACT_DIGEST, PICKLE_TYPE_PACK_PROVISION, PICKLE_REQUEST_TYPE_DOCUMENT } from "./resources.js";
+export declare const PICKLE_REQUEST_CONTRACT = "pickle.request";
+export declare const PICKLE_REQUEST_CONTRACT_VERSION = "1.0.0";
+export declare const PICKLE_NOTIFICATION_CRITERION = "pickle.request.created";
+export declare const PICKLE_NOTIFICATION_EVENT: {
+    readonly id: "mdbase.record.created";
+    readonly version: "1.0.0";
+    readonly digest: "sha256:7f3bed6baa356ee9389e977ae7b77a102e2bee871a7c1d9f2026fc21cacdbfc9";
+};
+export type PickleRequestState = "pending" | "answered" | "conflict" | "cancelled";
+export interface PickleFrontmatter extends JsonObject {
+    type?: string;
+    id?: string;
+    title?: string;
+    source?: string;
+    message?: string;
+    kind?: string;
+    status?: string;
+    priority?: string;
+    response_type?: string;
+    created_at?: string;
+    due_at?: string;
+    dedupe_key?: string;
+    tags?: unknown[];
+    links?: unknown[];
+    attachment_paths?: unknown[];
+    metadata?: JsonObject;
+}
+export interface PickleContractImplementation {
+    typeName: string;
+    fields: Record<string, string>;
+    binding?: JsonObject;
+    requestType: CollectionTypeDescriptor;
+}
+export interface PickleContract {
+    descriptor: CollectionContractDescriptor;
+    implementations: PickleContractImplementation[];
+}
+export interface PickleLink {
+    label: string;
+    url?: string;
+    path?: string;
+}
+export interface PickleAttachment {
+    path: string;
+    filename: string;
+}
+export interface PickleAttachmentContent {
+    path: string;
+    filename: string;
+    mediaType: string;
+    size: number;
+    blob: Blob;
+}
+export interface PickleResponse {
+    path: string;
+    type: string;
+    responder: string;
+    respondedAt?: string;
+    payload: JsonObject;
+    frontmatter: JsonObject;
+}
+export interface PickleRequest {
+    id: string;
+    path: string;
+    title: string;
+    source: string;
+    message: string;
+    body: string;
+    kind: string;
+    priority: string;
+    status?: string;
+    state: PickleRequestState;
+    responseCount: number;
+    responseType: string;
+    responseTypeDefinition?: CollectionTypeDescriptor;
+    createdAt?: string;
+    /** Stable file modification time for invalidating an opened context. */
+    modifiedAt?: string;
+    dueAt?: string;
+    tags: string[];
+    links: PickleLink[];
+    attachments: PickleAttachment[];
+    metadata: JsonObject;
+    response?: PickleResponse;
+    frontmatter: PickleFrontmatter;
+}
+export interface RespondOptions extends ConnectRequestOptions {
+    responder?: string;
+}
+export type PickleResponseSubmission = {
+    kind: "recorded";
+    record: RecordDocument<PickleFrontmatter>;
+} | {
+    kind: "pending";
+    requestId: string;
+};
+export type PicklePendingResponse = PendingMutation<RecordDocument<PickleFrontmatter>>;
+export interface PickleClient {
+    describe(options?: ConnectRequestOptions): ReturnType<MdbaseConnection<PickleFrontmatter>["describe"]>;
+    queryAll(input: Parameters<MdbaseConnection<PickleFrontmatter>["queryAll"]>[0], options?: Parameters<MdbaseConnection<PickleFrontmatter>["queryAll"]>[1]): ReturnType<MdbaseConnection<PickleFrontmatter>["queryAll"]>;
+    create(input: Parameters<MdbaseConnection<PickleFrontmatter>["create"]>[0], options?: ConnectRequestOptions): ReturnType<MdbaseConnection<PickleFrontmatter>["create"]>;
+    read(input: Parameters<MdbaseConnection<PickleFrontmatter>["read"]>[0], options?: ConnectRequestOptions): ReturnType<MdbaseConnection<PickleFrontmatter>["read"]>;
+    files: MdbaseConnection<PickleFrontmatter>["files"];
+    pendingMutations<Result = unknown>(): readonly PendingMutation<Result>[];
+    pendingMutation<Result = unknown>(requestId: string): PendingMutation<Result> | null;
+}
+export declare function resolvePickleContract(description: CollectionDescription): PickleContract;
+export declare class PickleCollection {
+    private readonly connect;
+    private description;
+    private contract;
+    constructor(connect: PickleClient);
+    describe(): Promise<{
+        collection: CollectionDescription;
+        contract: PickleContract;
+    }>;
+    describe(options: ConnectRequestOptions): Promise<{
+        collection: CollectionDescription;
+        contract: PickleContract;
+    }>;
+    /** Omit Markdown bodies for an inbox; load individual context with readBody. */
+    list({ includeBody, ...options }?: ConnectRequestOptions & {
+        includeBody?: boolean;
+    }): Promise<PickleRequest[]>;
+    readBody(request: Pick<PickleRequest, "path">, options?: ConnectRequestOptions): Promise<string>;
+    respond(request: PickleRequest, payload: JsonObject, options?: RespondOptions): Promise<PickleResponseSubmission>;
+    readAttachment(attachment: PickleAttachment, options?: ConnectRequestOptions): Promise<PickleAttachmentContent | null>;
+    pendingResponses(): readonly PicklePendingResponse[];
+    recoverResponse(requestId: string, options?: ConnectRequestOptions): Promise<PickleResponseSubmission>;
+}
+export declare class PickleContractError extends Error {
+}

package/dist/index.js

@@ -0,0 +1,350 @@
+import { MDBASE_RECORD_CREATED_CONTRACT, MdbaseConnectError } from "@mdbase-dev/connect";
+import { PICKLE_REQUEST_CONTRACT_DIGEST } from "./resources.js";
+export { PICKLE_ACK_RESPONSE_TYPE_DOCUMENT, PICKLE_ATTACHMENT_TYPE_DOCUMENT, PICKLE_APPROVAL_RESPONSE_TYPE_DOCUMENT, PICKLE_REQUEST_CONTRACT_DOCUMENT, PICKLE_REQUEST_CONTRACT_DIGEST, PICKLE_TYPE_PACK_PROVISION, PICKLE_REQUEST_TYPE_DOCUMENT } from "./resources.js";
+export const PICKLE_REQUEST_CONTRACT = "pickle.request";
+export const PICKLE_REQUEST_CONTRACT_VERSION = "1.0.0";
+export const PICKLE_NOTIFICATION_CRITERION = "pickle.request.created";
+export const PICKLE_NOTIFICATION_EVENT = MDBASE_RECORD_CREATED_CONTRACT;
+const SYSTEM_RESPONSE_FIELDS = new Set([
+    "type",
+    "types",
+    "id",
+    "request",
+    "responded_at",
+    "responder",
+    "attachment_paths"
+]);
+export function resolvePickleContract(description) {
+    const descriptor = description.contracts.find((contract) => contract.id === PICKLE_REQUEST_CONTRACT &&
+        contract.version === PICKLE_REQUEST_CONTRACT_VERSION &&
+        contract.digest === PICKLE_REQUEST_CONTRACT_DIGEST);
+    if (!descriptor) {
+        throw new PickleContractError("This collection does not provide the Pickle request contract.");
+    }
+    const implementations = descriptor.implementations.map((implementation) => {
+        const requestType = description.types.find((candidate) => candidate.name === implementation.typeName);
+        if (!requestType)
+            throw new PickleContractError(`The Pickle request type ${implementation.typeName} is missing from this collection.`);
+        return {
+            typeName: implementation.typeName,
+            fields: parseFields(implementation.fields),
+            binding: implementation.binding,
+            requestType
+        };
+    });
+    if (!implementations.length)
+        throw new PickleContractError("The Pickle request contract has no type implementations.");
+    return {
+        descriptor,
+        implementations
+    };
+}
+export class PickleCollection {
+    connect;
+    description = null;
+    contract = null;
+    constructor(connect) {
+        this.connect = connect;
+    }
+    async describe(options = {}) {
+        this.description ??= requireOutcome(await this.connect.describe(options));
+        this.contract ??= resolvePickleContract(this.description);
+        return { collection: this.description, contract: this.contract };
+    }
+    /** Omit Markdown bodies for an inbox; load individual context with readBody. */
+    async list({ includeBody = true, ...options } = {}) {
+        const { collection, contract } = await this.describe(options);
+        const requestQuery = requireOutcome(await this.connect.queryAll({
+            types: contract.implementations.map(({ typeName }) => typeName),
+            includeBody,
+            frontmatterMode: "effective"
+        }, { ...options, pageSize: 256 }));
+        const requests = requestQuery.results.map(requireEffectiveFrontmatter);
+        const responseTypes = [
+            ...new Set(requests
+                .map((record) => {
+                const implementation = implementationForRecord(contract, record);
+                return stringField(record.effectiveFrontmatter, role(implementation, "response_type", "response_type"));
+            })
+                .filter(Boolean))
+        ];
+        const responses = responseTypes.length
+            ? (requireOutcome(await this.connect.queryAll({
+                types: responseTypes,
+                includeBody: false,
+                frontmatterMode: "effective"
+            }, { ...options, pageSize: 256 }))).results.map(requireEffectiveFrontmatter)
+            : [];
+        return requests
+            .map((record) => normalizeRequest(record, responses, collection, contract))
+            .sort((left, right) => (right.createdAt ?? "").localeCompare(left.createdAt ?? ""));
+    }
+    async readBody(request, options = {}) {
+        const record = requireOutcome(await this.connect.read({ path: request.path }, options));
+        return record.body ?? "";
+    }
+    async respond(request, payload, options = {}) {
+        if (request.state !== "pending") {
+            throw new PickleContractError(request.state === "conflict"
+                ? "Resolve the conflicting responses in the collection first."
+                : "This request already has a response.");
+        }
+        const responseType = request.responseTypeDefinition;
+        if (!responseType) {
+            throw new PickleContractError(`The response type ${request.responseType} is unavailable.`);
+        }
+        const responseFolder = stringField(asObject(responseType.collection?.path), "folder") ||
+            "responses";
+        const { responder, ...requestOptions } = options;
+        const frontmatter = {
+            ...payload,
+            type: request.responseType,
+            request: requestLink(request.path),
+            responder: responder?.trim() || "human"
+        };
+        const created = await this.connect.create({
+            type: request.responseType,
+            path: `${trimSlashes(responseFolder)}/${crypto.randomUUID()}.md`,
+            frontmatter,
+            body: ""
+        }, requestOptions);
+        return responseSubmission(created);
+    }
+    async readAttachment(attachment, options = {}) {
+        const path = attachment.path.replace(/^\/+/, "");
+        if (isMarkdownPath(path)) {
+            const outcome = await this.connect.read({ path }, options);
+            if (outcome.ok) {
+                const frontmatter = outcome.value.frontmatter;
+                if (stringField(frontmatter, "type") === "pickle_attachment") {
+                    const body = outcome.value.body ?? "";
+                    const filename = stringField(frontmatter, "filename") || attachment.filename;
+                    const mediaType = stringField(frontmatter, "content_type") || "text/markdown";
+                    return {
+                        path,
+                        filename,
+                        mediaType,
+                        size: new TextEncoder().encode(body).byteLength,
+                        blob: new Blob([body], { type: mediaType })
+                    };
+                }
+            }
+        }
+        const separator = path.lastIndexOf("/");
+        const folder = separator < 0 ? undefined : path.slice(0, separator);
+        let match = null;
+        for await (const file of this.connect.files.list({
+            ...options,
+            ...(folder ? { folder } : {})
+        })) {
+            if (file.path === path) {
+                match = file;
+                break;
+            }
+        }
+        if (!match)
+            return null;
+        const blob = await this.connect.files.download(match, options);
+        return {
+            path,
+            filename: attachment.filename,
+            mediaType: match.mediaType || blob.type || "application/octet-stream",
+            size: match.size,
+            blob
+        };
+    }
+    pendingResponses() {
+        return this.connect
+            .pendingMutations()
+            .filter((mutation) => mutation.operation === "create");
+    }
+    async recoverResponse(requestId, options = {}) {
+        const pending = this.connect.pendingMutation(requestId);
+        if (!pending || pending.operation !== "create") {
+            throw new PickleContractError("This pending Pickle response is no longer available for recovery.");
+        }
+        return responseSubmission(await pending.recover(options));
+    }
+}
+export class PickleContractError extends Error {
+}
+function responseSubmission(outcome) {
+    if (outcome.ok)
+        return { kind: "recorded", record: outcome.value };
+    const requestId = outcome.problem.code === "operation_outcome_unknown" &&
+        outcome.problem.details &&
+        typeof outcome.problem.details === "object" &&
+        "request_id" in outcome.problem.details &&
+        typeof outcome.problem.details.request_id === "string"
+        ? outcome.problem.details.request_id
+        : null;
+    if (requestId)
+        return { kind: "pending", requestId };
+    throw new MdbaseConnectError(outcome.problem);
+}
+function normalizeRequest(record, responseRecords, description, contract) {
+    const implementation = implementationForRecord(contract, record);
+    const responseType = stringField(record.effectiveFrontmatter, role(implementation, "response_type", "response_type")) || "pickle_response_approval";
+    const linked = responseRecords.filter((candidate) => linkTargets(candidate.effectiveFrontmatter.request, record.path));
+    const status = stringField(record.effectiveFrontmatter, role(implementation, "status", "status"));
+    const state = status === "cancelled"
+        ? "cancelled"
+        : linked.length === 0
+            ? "pending"
+            : linked.length === 1
+                ? "answered"
+                : "conflict";
+    const response = linked.length === 1 ? normalizeResponse(linked[0]) : undefined;
+    return {
+        id: stringField(record.effectiveFrontmatter, role(implementation, "id", "id")) ||
+            record.path,
+        path: record.path,
+        title: stringField(record.effectiveFrontmatter, role(implementation, "title", "title")) ||
+            record.path,
+        source: stringField(record.effectiveFrontmatter, role(implementation, "source", "source")) ||
+            "agent",
+        message: stringField(record.effectiveFrontmatter, role(implementation, "message", "message")),
+        body: record.body ?? "",
+        modifiedAt: record.file?.mtime,
+        kind: stringField(record.effectiveFrontmatter, role(implementation, "kind", "kind")) ||
+            "approval",
+        priority: stringField(record.effectiveFrontmatter, role(implementation, "priority", "priority")) || "normal",
+        status: status || undefined,
+        state,
+        responseCount: linked.length,
+        responseType,
+        responseTypeDefinition: description.types.find((candidate) => candidate.name === responseType),
+        createdAt: stringField(record.effectiveFrontmatter, role(implementation, "created_at", "created_at")) || undefined,
+        dueAt: stringField(record.effectiveFrontmatter, "due_at") || undefined,
+        tags: stringList(getField(record.effectiveFrontmatter, role(implementation, "tags", "tags"))),
+        links: links(getField(record.effectiveFrontmatter, role(implementation, "links", "links"))),
+        attachments: attachments(getField(record.effectiveFrontmatter, role(implementation, "attachment_paths", "attachment_paths"))),
+        metadata: asObject(getField(record.effectiveFrontmatter, role(implementation, "metadata", "metadata"))) ?? {},
+        response,
+        frontmatter: record.effectiveFrontmatter
+    };
+}
+function normalizeResponse(record) {
+    const frontmatter = record.effectiveFrontmatter;
+    return {
+        path: record.path,
+        type: stringField(frontmatter, "type") || record.types[0] || "pickle_response",
+        responder: stringField(frontmatter, "responder") || "human",
+        respondedAt: stringField(frontmatter, "responded_at") || undefined,
+        payload: Object.fromEntries(Object.entries(frontmatter).filter(([key]) => !SYSTEM_RESPONSE_FIELDS.has(key))),
+        frontmatter
+    };
+}
+function requireEffectiveFrontmatter(record) {
+    if (!record.effectiveFrontmatter) {
+        throw new PickleContractError(`Query result ${record.path} omitted effectiveFrontmatter.`);
+    }
+    return record;
+}
+function requireOutcome(outcome) {
+    if (!outcome.ok)
+        throw new MdbaseConnectError(outcome.problem);
+    return outcome.value;
+}
+function parseFields(value) {
+    if (!Object.values(value).every((field) => typeof field === "string" && validFieldPath(field)))
+        throw new PickleContractError("The Pickle request contract is malformed.");
+    return value;
+}
+function role(implementation, name, fallback) {
+    return implementation.fields[name] ?? fallback;
+}
+function implementationForRecord(contract, record) {
+    const matches = contract.implementations.filter((implementation) => record.types.includes(implementation.typeName));
+    if (matches.length !== 1)
+        throw new PickleContractError(`Pickle request ${record.path} matches ${matches.length} contract implementations; exactly one is required.`);
+    return matches[0];
+}
+function getField(value, path) {
+    let current = value;
+    for (const segment of path.split(".")) {
+        const object = asObject(current);
+        if (!object)
+            return undefined;
+        current = object[segment];
+    }
+    return current;
+}
+function stringField(value, path) {
+    const field = asObject(value) ? getField(value, path) : undefined;
+    return typeof field === "string" ? field.trim() : "";
+}
+function stringList(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+function links(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item) => {
+        const object = asObject(item);
+        if (!object)
+            return [];
+        const label = stringField(object, "label");
+        const url = stringField(object, "url");
+        const path = stringField(object, "path");
+        return label || url || path
+            ? [{ label: label || url || path, ...(url ? { url } : {}), ...(path ? { path } : {}) }]
+            : [];
+    });
+}
+function attachments(value) {
+    return stringList(value).map((path) => ({
+        path,
+        filename: path.split("/").at(-1) || path
+    }));
+}
+function requestLink(path) {
+    return `[[${path.replace(/\.md$/i, "")}]]`;
+}
+function linkTargets(value, requestPath) {
+    if (typeof value !== "string")
+        return false;
+    const target = normalizeLink(value);
+    const request = normalizeLink(requestPath);
+    if (!target || !request)
+        return false;
+    return (target === request ||
+        (!target.includes("/") && target === request.split("/").at(-1)));
+}
+function normalizeLink(value) {
+    let normalized = value.trim();
+    if (normalized.startsWith("[[") && normalized.endsWith("]]")) {
+        normalized = normalized.slice(2, -2);
+    }
+    else {
+        const markdown = normalized.match(/^\[[^\]]*\]\(([^)]+)\)$/);
+        if (markdown)
+            normalized = markdown[1];
+    }
+    normalized = normalized.split("|", 1)[0].split("#", 1)[0];
+    return normalized
+        .replaceAll("\\", "/")
+        .replace(/^\.?\//, "")
+        .replace(/\.md$/i, "");
+}
+function validFieldPath(value) {
+    return value
+        .split(".")
+        .every((part) => part.length > 0 &&
+        part !== "__proto__" &&
+        part !== "prototype" &&
+        part !== "constructor");
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+function isMarkdownPath(path) {
+    return /\.(?:md|markdown|mdown|mkd|mkdn)$/i.test(path);
+}
+function asObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}

package/dist/resources.d.ts

@@ -0,0 +1,68 @@
+export declare const PICKLE_REQUEST_CONTRACT_DOCUMENT = "---\nkind: mdbase.contract\ncontract_type: record\nid: pickle.request\nversion: 1.0.0\nname: Pickle request\ndescription: A portable asynchronous request that needs a human response.\nrecord_schema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [title, response_type]\n    properties:\n      id: { type: string }\n      title: { type: string, minLength: 1 }\n      source: { type: string }\n      message: { type: string }\n      kind: { enum: [approval, choice, input, notice, message] }\n      status: { enum: [pending, answered, cancelled] }\n      priority: { enum: [low, normal, high, urgent] }\n      response_type: { type: string }\n      created_at: { type: string, format: date-time }\n      tags:\n        type: array\n        items: { type: string }\n      links:\n        type: array\n        items:\n          type: object\n          additionalProperties: false\n          properties:\n            label: { type: string }\n            url: { type: string }\n            path: { type: string }\n      attachment_paths:\n        type: array\n        items: { type: string }\n      metadata:\n        type: object\n        additionalProperties: true\n---\n";
+/** Semantic digest of the resolved Pickle request contract, pinned by consumers. */
+export declare const PICKLE_REQUEST_CONTRACT_DIGEST = "sha256:5a96bbda301de6ec2f71a5083f62769463b4e613ed8ba860d62170b8c810db61";
+export declare const PICKLE_REQUEST_TYPE_DOCUMENT = "---\nkind: mdbase.type\nname: pickle_request\nversion: 1\ndescription: Async request that needs a human response.\nschema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [title, response_type]\n    properties:\n      type: { const: pickle_request }\n      id: { type: string }\n      title: { type: string, minLength: 1 }\n      source: { type: string }\n      message: { type: string }\n      kind: { enum: [approval, choice, input, notice, message] }\n      status:\n        enum: [pending, answered, cancelled]\n        description: Legacy lifecycle marker. Response links are authoritative for answered state.\n      priority: { enum: [low, normal, high, urgent] }\n      response_type: { type: string }\n      created_at: { type: string, format: date-time }\n      due_at: { type: string, format: date-time }\n      dedupe_key: { type: string }\n      tags:\n        type: array\n        items: { type: string }\n      links:\n        type: array\n        items:\n          type: object\n          additionalProperties: false\n          properties:\n            label: { type: string }\n            url: { type: string }\n            path: { type: string }\n      attachment_paths:\n        type: array\n        items: { type: string }\n      metadata:\n        type: object\n        additionalProperties: true\n      context:\n        type: object\n        additionalProperties: false\n        properties:\n          cwd: { type: string }\n          repo: { type: string }\n          task: { type: string }\ncollection:\n  display:\n    name_field: title\n  unique:\n    - field: id\n      scope: collection\nlifecycle:\n  on_create:\n    set:\n      created_at: { now: true }\nimplements:\n  - contract: pickle.request\n    version: 1.0.0\n    fields:\n      id: id\n      title: title\n      source: source\n      message: message\n      kind: kind\n      status: status\n      priority: priority\n      response_type: response_type\n      created_at: created_at\n      tags: tags\n      links: links\n      attachment_paths: attachment_paths\n      metadata: metadata\n---\n";
+export declare const PICKLE_APPROVAL_RESPONSE_TYPE_DOCUMENT = "---\nkind: mdbase.type\nname: pickle_response_approval\nversion: 1\ndescription: Approve, reject, or request revision for a Pickle request.\nschema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [request, decision]\n    properties:\n      type: { const: pickle_response_approval }\n      id: { type: string }\n      request: { type: string }\n      decision: { enum: [approve, reject, revise] }\n      comment: { type: string }\n      responded_at: { type: string, format: date-time }\n      responder: { type: string }\n      attachment_paths:\n        type: array\n        items: { type: string }\ncollection:\n  display:\n    name_field: decision\n  links:\n    request:\n      target_type: pickle_request\n      validate_exists: true\n  unique:\n    - field: id\n      scope: collection\nlifecycle:\n  on_create:\n    set:\n      id: { ulid: true }\n      responded_at: { now: true }\n---\n";
+export declare const PICKLE_ACK_RESPONSE_TYPE_DOCUMENT = "---\nkind: mdbase.type\nname: pickle_response_ack\nversion: 1\ndescription: Acknowledge that a Pickle message was read.\nschema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [request]\n    properties:\n      type: { const: pickle_response_ack }\n      id: { type: string }\n      request: { type: string }\n      message: { type: string }\n      responded_at: { type: string, format: date-time }\n      responder: { type: string }\n      attachment_paths:\n        type: array\n        items: { type: string }\ncollection:\n  display:\n    name_field: message\n  links:\n    request:\n      target_type: pickle_request\n      validate_exists: true\n  unique:\n    - field: id\n      scope: collection\nlifecycle:\n  on_create:\n    set:\n      id: { ulid: true }\n      responded_at: { now: true }\n---\n";
+export declare const PICKLE_ATTACHMENT_TYPE_DOCUMENT = "---\nkind: mdbase.type\nname: pickle_attachment\nversion: 1\ndescription: Markdown content attached to a Pickle request.\nschema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [request_id, filename, content_type, size_bytes, sha256]\n    properties:\n      type: { const: pickle_attachment }\n      request_id: { type: string, minLength: 1 }\n      filename: { type: string, minLength: 1 }\n      content_type: { type: string, minLength: 1 }\n      size_bytes: { type: integer, minimum: 0 }\n      sha256: { type: string, pattern: '^sha256:[0-9a-f]{64}$' }\n      created_at: { type: string, format: date-time }\ncollection:\n  display:\n    name_field: filename\n---\n";
+export declare const PICKLE_TYPE_PACK_PROVISION: {
+    readonly manifest: {
+        readonly kind: "mdbase.type-pack";
+        readonly id: "pickle.requests";
+        readonly version: "1.1.0";
+        readonly name: "Pickle requests";
+        readonly description: "Pickle request and response record types.";
+        readonly resources: readonly [{
+            readonly kind: "contract";
+            readonly mode: "managed";
+            readonly source: "contracts/pickle.request.md";
+            readonly target: "_contracts/pickle.request.md";
+            readonly digest: "sha256:caf9ee290e98ef51f871a1237b38531168aa1b74640241ce6edece4c2bff66f1";
+        }, {
+            readonly kind: "type";
+            readonly mode: "seed";
+            readonly source: "types/pickle_request.md";
+            readonly target: "_types/pickle_request.md";
+            readonly digest: "sha256:7f84e359a5a3b7d23dd3471c7557f67cb8a80eb553184db83c4750b2af5761e4";
+        }, {
+            readonly kind: "type";
+            readonly mode: "seed";
+            readonly source: "types/pickle_response_approval.md";
+            readonly target: "_types/pickle_response_approval.md";
+            readonly digest: "sha256:944d2b68c158297f5d2a035fa6ff3c81a7098531f77a9bc3342dc9435ffcb8b8";
+        }, {
+            readonly kind: "type";
+            readonly mode: "seed";
+            readonly source: "types/pickle_response_ack.md";
+            readonly target: "_types/pickle_response_ack.md";
+            readonly digest: "sha256:2530c8d21bb711889f20e0d096045cb6c9a7618583b1e2afff7ada72367de41f";
+        }, {
+            readonly kind: "type";
+            readonly mode: "seed";
+            readonly source: "types/pickle_attachment.md";
+            readonly target: "_types/pickle_attachment.md";
+            readonly digest: "sha256:67f14eeee2c126e99d8b37b7508fa148955b924367e2d2941b1793d1c814ec25";
+        }];
+    };
+    readonly resources: readonly [{
+        readonly source: "contracts/pickle.request.md";
+        readonly document: "---\nkind: mdbase.contract\ncontract_type: record\nid: pickle.request\nversion: 1.0.0\nname: Pickle request\ndescription: A portable asynchronous request that needs a human response.\nrecord_schema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [title, response_type]\n    properties:\n      id: { type: string }\n      title: { type: string, minLength: 1 }\n      source: { type: string }\n      message: { type: string }\n      kind: { enum: [approval, choice, input, notice, message] }\n      status: { enum: [pending, answered, cancelled] }\n      priority: { enum: [low, normal, high, urgent] }\n      response_type: { type: string }\n      created_at: { type: string, format: date-time }\n      tags:\n        type: array\n        items: { type: string }\n      links:\n        type: array\n        items:\n          type: object\n          additionalProperties: false\n          properties:\n            label: { type: string }\n            url: { type: string }\n            path: { type: string }\n      attachment_paths:\n        type: array\n        items: { type: string }\n      metadata:\n        type: object\n        additionalProperties: true\n---\n";
+    }, {
+        readonly source: "types/pickle_request.md";
+        readonly document: "---\nkind: mdbase.type\nname: pickle_request\nversion: 1\ndescription: Async request that needs a human response.\nschema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [title, response_type]\n    properties:\n      type: { const: pickle_request }\n      id: { type: string }\n      title: { type: string, minLength: 1 }\n      source: { type: string }\n      message: { type: string }\n      kind: { enum: [approval, choice, input, notice, message] }\n      status:\n        enum: [pending, answered, cancelled]\n        description: Legacy lifecycle marker. Response links are authoritative for answered state.\n      priority: { enum: [low, normal, high, urgent] }\n      response_type: { type: string }\n      created_at: { type: string, format: date-time }\n      due_at: { type: string, format: date-time }\n      dedupe_key: { type: string }\n      tags:\n        type: array\n        items: { type: string }\n      links:\n        type: array\n        items:\n          type: object\n          additionalProperties: false\n          properties:\n            label: { type: string }\n            url: { type: string }\n            path: { type: string }\n      attachment_paths:\n        type: array\n        items: { type: string }\n      metadata:\n        type: object\n        additionalProperties: true\n      context:\n        type: object\n        additionalProperties: false\n        properties:\n          cwd: { type: string }\n          repo: { type: string }\n          task: { type: string }\ncollection:\n  display:\n    name_field: title\n  unique:\n    - field: id\n      scope: collection\nlifecycle:\n  on_create:\n    set:\n      created_at: { now: true }\nimplements:\n  - contract: pickle.request\n    version: 1.0.0\n    fields:\n      id: id\n      title: title\n      source: source\n      message: message\n      kind: kind\n      status: status\n      priority: priority\n      response_type: response_type\n      created_at: created_at\n      tags: tags\n      links: links\n      attachment_paths: attachment_paths\n      metadata: metadata\n---\n";
+    }, {
+        readonly source: "types/pickle_response_approval.md";
+        readonly document: "---\nkind: mdbase.type\nname: pickle_response_approval\nversion: 1\ndescription: Approve, reject, or request revision for a Pickle request.\nschema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [request, decision]\n    properties:\n      type: { const: pickle_response_approval }\n      id: { type: string }\n      request: { type: string }\n      decision: { enum: [approve, reject, revise] }\n      comment: { type: string }\n      responded_at: { type: string, format: date-time }\n      responder: { type: string }\n      attachment_paths:\n        type: array\n        items: { type: string }\ncollection:\n  display:\n    name_field: decision\n  links:\n    request:\n      target_type: pickle_request\n      validate_exists: true\n  unique:\n    - field: id\n      scope: collection\nlifecycle:\n  on_create:\n    set:\n      id: { ulid: true }\n      responded_at: { now: true }\n---\n";
+    }, {
+        readonly source: "types/pickle_response_ack.md";
+        readonly document: "---\nkind: mdbase.type\nname: pickle_response_ack\nversion: 1\ndescription: Acknowledge that a Pickle message was read.\nschema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [request]\n    properties:\n      type: { const: pickle_response_ack }\n      id: { type: string }\n      request: { type: string }\n      message: { type: string }\n      responded_at: { type: string, format: date-time }\n      responder: { type: string }\n      attachment_paths:\n        type: array\n        items: { type: string }\ncollection:\n  display:\n    name_field: message\n  links:\n    request:\n      target_type: pickle_request\n      validate_exists: true\n  unique:\n    - field: id\n      scope: collection\nlifecycle:\n  on_create:\n    set:\n      id: { ulid: true }\n      responded_at: { now: true }\n---\n";
+    }, {
+        readonly source: "types/pickle_attachment.md";
+        readonly document: "---\nkind: mdbase.type\nname: pickle_attachment\nversion: 1\ndescription: Markdown content attached to a Pickle request.\nschema:\n  dialect: json-schema-2020-12\n  value:\n    $schema: \"https://json-schema.org/draft/2020-12/schema\"\n    type: object\n    additionalProperties: true\n    required: [request_id, filename, content_type, size_bytes, sha256]\n    properties:\n      type: { const: pickle_attachment }\n      request_id: { type: string, minLength: 1 }\n      filename: { type: string, minLength: 1 }\n      content_type: { type: string, minLength: 1 }\n      size_bytes: { type: integer, minimum: 0 }\n      sha256: { type: string, pattern: '^sha256:[0-9a-f]{64}$' }\n      created_at: { type: string, format: date-time }\ncollection:\n  display:\n    name_field: filename\n---\n";
+    }];
+    readonly provides: readonly [{
+        readonly id: "pickle.request";
+        readonly version: "1.0.0";
+        readonly digest: "sha256:5a96bbda301de6ec2f71a5083f62769463b4e613ed8ba860d62170b8c810db61";
+    }];
+};

package/dist/resources.js

@@ -0,0 +1,304 @@
+export const PICKLE_REQUEST_CONTRACT_DOCUMENT = `---
+kind: mdbase.contract
+contract_type: record
+id: pickle.request
+version: 1.0.0
+name: Pickle request
+description: A portable asynchronous request that needs a human response.
+record_schema:
+  dialect: json-schema-2020-12
+  value:
+    $schema: "https://json-schema.org/draft/2020-12/schema"
+    type: object
+    additionalProperties: true
+    required: [title, response_type]
+    properties:
+      id: { type: string }
+      title: { type: string, minLength: 1 }
+      source: { type: string }
+      message: { type: string }
+      kind: { enum: [approval, choice, input, notice, message] }
+      status: { enum: [pending, answered, cancelled] }
+      priority: { enum: [low, normal, high, urgent] }
+      response_type: { type: string }
+      created_at: { type: string, format: date-time }
+      tags:
+        type: array
+        items: { type: string }
+      links:
+        type: array
+        items:
+          type: object
+          additionalProperties: false
+          properties:
+            label: { type: string }
+            url: { type: string }
+            path: { type: string }
+      attachment_paths:
+        type: array
+        items: { type: string }
+      metadata:
+        type: object
+        additionalProperties: true
+---
+`;
+/** Semantic digest of the resolved Pickle request contract, pinned by consumers. */
+export const PICKLE_REQUEST_CONTRACT_DIGEST = "sha256:5a96bbda301de6ec2f71a5083f62769463b4e613ed8ba860d62170b8c810db61";
+export const PICKLE_REQUEST_TYPE_DOCUMENT = `---
+kind: mdbase.type
+name: pickle_request
+version: 1
+description: Async request that needs a human response.
+schema:
+  dialect: json-schema-2020-12
+  value:
+    $schema: "https://json-schema.org/draft/2020-12/schema"
+    type: object
+    additionalProperties: true
+    required: [title, response_type]
+    properties:
+      type: { const: pickle_request }
+      id: { type: string }
+      title: { type: string, minLength: 1 }
+      source: { type: string }
+      message: { type: string }
+      kind: { enum: [approval, choice, input, notice, message] }
+      status:
+        enum: [pending, answered, cancelled]
+        description: Legacy lifecycle marker. Response links are authoritative for answered state.
+      priority: { enum: [low, normal, high, urgent] }
+      response_type: { type: string }
+      created_at: { type: string, format: date-time }
+      due_at: { type: string, format: date-time }
+      dedupe_key: { type: string }
+      tags:
+        type: array
+        items: { type: string }
+      links:
+        type: array
+        items:
+          type: object
+          additionalProperties: false
+          properties:
+            label: { type: string }
+            url: { type: string }
+            path: { type: string }
+      attachment_paths:
+        type: array
+        items: { type: string }
+      metadata:
+        type: object
+        additionalProperties: true
+      context:
+        type: object
+        additionalProperties: false
+        properties:
+          cwd: { type: string }
+          repo: { type: string }
+          task: { type: string }
+collection:
+  display:
+    name_field: title
+  unique:
+    - field: id
+      scope: collection
+lifecycle:
+  on_create:
+    set:
+      created_at: { now: true }
+implements:
+  - contract: pickle.request
+    version: 1.0.0
+    fields:
+      id: id
+      title: title
+      source: source
+      message: message
+      kind: kind
+      status: status
+      priority: priority
+      response_type: response_type
+      created_at: created_at
+      tags: tags
+      links: links
+      attachment_paths: attachment_paths
+      metadata: metadata
+---
+`;
+export const PICKLE_APPROVAL_RESPONSE_TYPE_DOCUMENT = `---
+kind: mdbase.type
+name: pickle_response_approval
+version: 1
+description: Approve, reject, or request revision for a Pickle request.
+schema:
+  dialect: json-schema-2020-12
+  value:
+    $schema: "https://json-schema.org/draft/2020-12/schema"
+    type: object
+    additionalProperties: true
+    required: [request, decision]
+    properties:
+      type: { const: pickle_response_approval }
+      id: { type: string }
+      request: { type: string }
+      decision: { enum: [approve, reject, revise] }
+      comment: { type: string }
+      responded_at: { type: string, format: date-time }
+      responder: { type: string }
+      attachment_paths:
+        type: array
+        items: { type: string }
+collection:
+  display:
+    name_field: decision
+  links:
+    request:
+      target_type: pickle_request
+      validate_exists: true
+  unique:
+    - field: id
+      scope: collection
+lifecycle:
+  on_create:
+    set:
+      id: { ulid: true }
+      responded_at: { now: true }
+---
+`;
+export const PICKLE_ACK_RESPONSE_TYPE_DOCUMENT = `---
+kind: mdbase.type
+name: pickle_response_ack
+version: 1
+description: Acknowledge that a Pickle message was read.
+schema:
+  dialect: json-schema-2020-12
+  value:
+    $schema: "https://json-schema.org/draft/2020-12/schema"
+    type: object
+    additionalProperties: true
+    required: [request]
+    properties:
+      type: { const: pickle_response_ack }
+      id: { type: string }
+      request: { type: string }
+      message: { type: string }
+      responded_at: { type: string, format: date-time }
+      responder: { type: string }
+      attachment_paths:
+        type: array
+        items: { type: string }
+collection:
+  display:
+    name_field: message
+  links:
+    request:
+      target_type: pickle_request
+      validate_exists: true
+  unique:
+    - field: id
+      scope: collection
+lifecycle:
+  on_create:
+    set:
+      id: { ulid: true }
+      responded_at: { now: true }
+---
+`;
+export const PICKLE_ATTACHMENT_TYPE_DOCUMENT = `---
+kind: mdbase.type
+name: pickle_attachment
+version: 1
+description: Markdown content attached to a Pickle request.
+schema:
+  dialect: json-schema-2020-12
+  value:
+    $schema: "https://json-schema.org/draft/2020-12/schema"
+    type: object
+    additionalProperties: true
+    required: [request_id, filename, content_type, size_bytes, sha256]
+    properties:
+      type: { const: pickle_attachment }
+      request_id: { type: string, minLength: 1 }
+      filename: { type: string, minLength: 1 }
+      content_type: { type: string, minLength: 1 }
+      size_bytes: { type: integer, minimum: 0 }
+      sha256: { type: string, pattern: '^sha256:[0-9a-f]{64}$' }
+      created_at: { type: string, format: date-time }
+collection:
+  display:
+    name_field: filename
+---
+`;
+export const PICKLE_TYPE_PACK_PROVISION = {
+    manifest: {
+        kind: "mdbase.type-pack",
+        id: "pickle.requests",
+        version: "1.1.0",
+        name: "Pickle requests",
+        description: "Pickle request and response record types.",
+        resources: [
+            {
+                kind: "contract",
+                mode: "managed",
+                source: "contracts/pickle.request.md",
+                target: "_contracts/pickle.request.md",
+                digest: "sha256:caf9ee290e98ef51f871a1237b38531168aa1b74640241ce6edece4c2bff66f1"
+            },
+            {
+                kind: "type",
+                mode: "seed",
+                source: "types/pickle_request.md",
+                target: "_types/pickle_request.md",
+                digest: "sha256:7f84e359a5a3b7d23dd3471c7557f67cb8a80eb553184db83c4750b2af5761e4"
+            },
+            {
+                kind: "type",
+                mode: "seed",
+                source: "types/pickle_response_approval.md",
+                target: "_types/pickle_response_approval.md",
+                digest: "sha256:944d2b68c158297f5d2a035fa6ff3c81a7098531f77a9bc3342dc9435ffcb8b8"
+            },
+            {
+                kind: "type",
+                mode: "seed",
+                source: "types/pickle_response_ack.md",
+                target: "_types/pickle_response_ack.md",
+                digest: "sha256:2530c8d21bb711889f20e0d096045cb6c9a7618583b1e2afff7ada72367de41f"
+            },
+            {
+                kind: "type",
+                mode: "seed",
+                source: "types/pickle_attachment.md",
+                target: "_types/pickle_attachment.md",
+                digest: "sha256:67f14eeee2c126e99d8b37b7508fa148955b924367e2d2941b1793d1c814ec25"
+            }
+        ]
+    },
+    resources: [
+        {
+            source: "contracts/pickle.request.md",
+            document: PICKLE_REQUEST_CONTRACT_DOCUMENT
+        },
+        {
+            source: "types/pickle_request.md",
+            document: PICKLE_REQUEST_TYPE_DOCUMENT
+        },
+        {
+            source: "types/pickle_response_approval.md",
+            document: PICKLE_APPROVAL_RESPONSE_TYPE_DOCUMENT
+        },
+        {
+            source: "types/pickle_response_ack.md",
+            document: PICKLE_ACK_RESPONSE_TYPE_DOCUMENT
+        },
+        {
+            source: "types/pickle_attachment.md",
+            document: PICKLE_ATTACHMENT_TYPE_DOCUMENT
+        }
+    ],
+    provides: [{
+            id: "pickle.request",
+            version: "1.0.0",
+            digest: PICKLE_REQUEST_CONTRACT_DIGEST
+        }]
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mdbase-dev/pickle",
+  "version": "0.1.0-beta.100",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdbase-dev/mdbase-connect.git",
+    "directory": "packages/pickle"
+  },
+  "homepage": "https://mdbase.dev",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@mdbase-dev/connect": "0.1.0-beta.100"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10",
+    "@mdbase-dev/connect-dev": "0.1.0-beta.100",
+    "@mdbase-dev/connect-testing": "0.1.0-beta.100"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}