@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/git-wire.d.ts

@@ -0,0 +1,33 @@
+/** Git smart-HTTP packet grammar shared by host doors and CAS writers. */
+import type { GitPushVerdict, GitRefUpdate } from "./git.js";
+/** Split pkt-lines from the start of `bytes`; stops at the first flush when asked. */
+export declare function readPacketLines(bytes: Uint8Array, stopAtFlush: boolean, strict?: boolean): Uint8Array[];
+/** Encode one UTF-8 text packet with its byte-counted four-byte Git header. */
+export declare function pktLine(text: string): string;
+/** Refs the provider accepted, read from report-status (with or without side-band). */
+export declare function acceptedRefs(response: Uint8Array, sideBand: boolean): ReadonlySet<string>;
+/** The decoded receive-pack command section; pack bytes remain unopened. */
+export type ReceivePack = Readonly<{
+    kind: "ok";
+    updates: readonly GitRefUpdate[];
+    capabilities: readonly string[];
+}> | Readonly<{
+    /** A lone flush: the probe Git sends before a chunked (large) push to
+     * check authentication; it updates nothing. */
+    kind: "probe";
+}> | Readonly<{
+    kind: "invalid";
+    reason: "unparsable" | "push-cert" | "too-many";
+}>;
+/** Fail closed on any command the maintained Git wire contract does not support. */
+export declare function parseReceivePack(body: Uint8Array): ReceivePack;
+/** Whole-push refusal in report-status, including the negotiated side-band framing. */
+export declare function refusalReport(verdict: GitPushVerdict & {
+    allowed: false;
+}, updates: readonly GitRefUpdate[], capabilities: readonly string[]): Uint8Array;
+/** Data channel of an upload-pack side-band reply; fatal server messages refuse. */
+export declare function sideBandData(body: Uint8Array): Uint8Array;
+/** Ref names and object IDs from the maintained smart-HTTP advertisement framing. */
+export declare function advertisedRefs(body: Uint8Array): ReadonlyMap<string, string>;
+/** Capabilities from the ref advertisement's first NUL-delimited capability list. */
+export declare function advertisedCapabilities(body: Uint8Array): ReadonlySet<string>;

package/dist/git-wire.js

@@ -0,0 +1,240 @@
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+const ZERO = "0".repeat(40);
+const pushDecoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+class InvalidPushRequest extends Error {
+    reason;
+    constructor(message, options, reason = "unparsable") {
+        super(message, options);
+        this.reason = reason;
+    }
+}
+/** Strict client headers must be hexadecimal; provider status retains tolerant decoding. */
+function packetHeader(bytes, offset, strict) {
+    const header = decoder.decode(bytes.subarray(offset, offset + 4));
+    if (strict && !/^[0-9a-f]{4}$/iu.test(header))
+        throw new InvalidPushRequest("Invalid Git push packet");
+    return Number.parseInt(header, 16);
+}
+/** Decode one packet's framing without consuming payload or a following pack. */
+function packetLength(bytes, offset, strict) {
+    const length = packetHeader(bytes, offset, strict);
+    if (Number.isNaN(length))
+        return null;
+    if (strict && length === 1)
+        throw new InvalidPushRequest("Unsupported Git push delimiter");
+    if (length <= 1)
+        return length;
+    if (length < 4 || offset + length > bytes.length) {
+        if (strict)
+            throw new InvalidPushRequest("Truncated Git push packet");
+        return null;
+    }
+    return length;
+}
+/** Command bounds apply before decoding; provider status packets remain tolerant. */
+function packetContent(bytes, offset, length, count, strict) {
+    if (strict && count >= 256)
+        throw new InvalidPushRequest("Too many Git push commands", undefined, "too-many");
+    return bytes.subarray(offset + 4, offset + length);
+}
+/** Split pkt-lines from the start of `bytes`; stops at the first flush when asked. */
+export function readPacketLines(bytes, stopAtFlush, strict = false) {
+    const lines = [];
+    let offset = 0;
+    let flushed = false;
+    while (offset + 4 <= bytes.length) {
+        const length = packetLength(bytes, offset, strict);
+        if (length === null)
+            break;
+        if (length <= 1) {
+            offset += 4;
+            if (stopAtFlush && length === 0) {
+                flushed = true;
+                break;
+            }
+            continue;
+        }
+        lines.push(packetContent(bytes, offset, length, lines.length, strict));
+        offset += length;
+    }
+    if (strict && !flushed)
+        throw new InvalidPushRequest("Git push command section has no flush");
+    return lines;
+}
+/** Encode one UTF-8 text packet with its byte-counted four-byte Git header. */
+export function pktLine(text) {
+    return (encoder.encode(text).length + 4).toString(16).padStart(4, "0") + text;
+}
+const COMMAND = /^([0-9a-f]{40}) ([0-9a-f]{40}) (refs\/[^\s\0]+)$/iu;
+/** A shallow client's graft boundary, sent before its commands
+ * (pack-protocol `update-request = *shallow command-list`). */
+const SHALLOW = /^shallow [0-9a-f]{40}\n?$/iu;
+/** Decode exactly the command and optional capability fields supplied by the client. */
+function pushFields(raw) {
+    let text;
+    try {
+        text = pushDecoder.decode(raw);
+    }
+    catch (cause) {
+        throw new InvalidPushRequest("Invalid Git push command encoding", {
+            cause,
+        });
+    }
+    const fields = text.replace(/\n$/u, "").split("\0");
+    if (fields.length > 2)
+        throw new InvalidPushRequest("Invalid Git push command capabilities");
+    return fields;
+}
+function refCommand(line) {
+    const match = COMMAND.exec(line);
+    if (!match) {
+        const signed = line.startsWith("push-cert");
+        throw new InvalidPushRequest(signed ? "Unsupported push-cert command" : "Unsupported Git push command", undefined, signed ? "push-cert" : "unparsable");
+    }
+    const [, before = ZERO, after = ZERO, ref = ""] = match;
+    return { before: before.toLowerCase(), after: after.toLowerCase(), ref };
+}
+function pushCapabilities(caps, commandIndex) {
+    if (caps === undefined)
+        return undefined;
+    if (commandIndex !== 0)
+        throw new InvalidPushRequest("Git push capabilities must accompany the first command");
+    const capabilities = caps.split(" ").filter(Boolean);
+    if (capabilities.some((capability) => capability === "push-cert" || capability.startsWith("push-cert=")))
+        throw new InvalidPushRequest("Signed Git pushes (push-cert) are not supported", undefined, "push-cert");
+    return capabilities;
+}
+/** The ref commands a client sends before its pack, and its capabilities. */
+function pushRequest(body) {
+    const commands = [];
+    let capabilities = [];
+    const lines = readPacketLines(body, true, true);
+    // A push from a shallow repository (for example a `--depth 1` clone)
+    // names its graft boundaries first; the server only needs the commands.
+    const first = lines.findIndex((line) => !SHALLOW.test(decoder.decode(line)));
+    for (const raw of first === -1 ? [] : lines.slice(first)) {
+        const [line = "", caps] = pushFields(raw);
+        const command = refCommand(line);
+        const nextCapabilities = pushCapabilities(caps, commands.length);
+        commands.push(command);
+        if (nextCapabilities !== undefined)
+            capabilities = nextCapabilities;
+    }
+    if (commands.length === 0)
+        throw new InvalidPushRequest("Empty Git push command section");
+    return { commands, capabilities };
+}
+/** Refs the provider accepted, read from report-status (with or without side-band). */
+export function acceptedRefs(response, sideBand) {
+    let status = response;
+    if (sideBand) {
+        const parts = readPacketLines(response, false)
+            .filter((line) => line[0] === 1)
+            .map((line) => line.subarray(1));
+        status = new Uint8Array(parts.reduce((size, part) => size + part.length, 0));
+        let offset = 0;
+        for (const part of parts) {
+            status.set(part, offset);
+            offset += part.length;
+        }
+    }
+    const accepted = new Set();
+    for (const raw of readPacketLines(status, false)) {
+        const text = decoder.decode(raw).replace(/\n$/u, "");
+        if (text.startsWith("ok "))
+            accepted.add(text.slice(3));
+    }
+    return accepted;
+}
+/** Fail closed on any command the maintained Git wire contract does not support. */
+export function parseReceivePack(body) {
+    if (body.byteLength === 4 && decoder.decode(body) === "0000")
+        return { kind: "probe" };
+    try {
+        const push = pushRequest(body);
+        return {
+            kind: "ok",
+            updates: push.commands,
+            capabilities: push.capabilities,
+        };
+    }
+    catch (cause) {
+        if (!(cause instanceof InvalidPushRequest))
+            throw cause;
+        return { kind: "invalid", reason: cause.reason };
+    }
+}
+/** Whole-push refusal in report-status, including the negotiated side-band framing. */
+export function refusalReport(verdict, updates, capabilities) {
+    const messages = new Map(verdict.refused.map(({ ref, message }) => [ref, message]));
+    const report = pktLine("unpack ok\n") +
+        updates
+            .map(({ ref }) => pktLine(`ng ${ref} ${(messages.get(ref) ?? "another ref in this push was refused").replace(/[\r\n\0]/gu, " ")}\n`))
+            .join("") +
+        "0000";
+    if (!capabilities.includes("side-band") &&
+        !capabilities.includes("side-band-64k"))
+        return encoder.encode(report);
+    const bytes = encoder.encode(report);
+    const chunkSize = capabilities.includes("side-band-64k") ? 65515 : 995;
+    const chunks = Math.ceil(bytes.byteLength / chunkSize);
+    const output = new Uint8Array(bytes.byteLength + chunks * 5 + 4);
+    let offset = 0;
+    for (let start = 0; start < bytes.byteLength; start += chunkSize) {
+        const chunk = bytes.subarray(start, start + chunkSize);
+        output.set(encoder.encode((chunk.byteLength + 5).toString(16).padStart(4, "0")), offset);
+        output[offset + 4] = 1;
+        output.set(chunk, offset + 5);
+        offset += chunk.byteLength + 5;
+    }
+    output.set(encoder.encode("0000"), offset);
+    return output;
+}
+/** Data channel of an upload-pack side-band reply; fatal server messages refuse. */
+export function sideBandData(body) {
+    const chunks = [];
+    for (const packet of readPacketLines(body, false)) {
+        if (packet[0] === 3)
+            throw new Error(decoder.decode(packet.subarray(1)));
+        if (packet[0] === 1)
+            chunks.push(packet.subarray(1));
+        else if (decoder.decode(packet).startsWith("ERR "))
+            throw new Error(decoder.decode(packet));
+    }
+    const result = new Uint8Array(chunks.reduce((size, chunk) => size + chunk.length, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return result;
+}
+/** Ref names and object IDs from the maintained smart-HTTP advertisement framing. */
+export function advertisedRefs(body) {
+    const refs = new Map();
+    for (const raw of readPacketLines(body, false)) {
+        const line = decoder.decode(raw).replace(/\n$/u, "");
+        if (line.startsWith("#"))
+            continue;
+        const [entry = ""] = line.split("\0");
+        const [oid = "", name = ""] = entry.split(" ");
+        if (/^[0-9a-f]{40}$/u.test(oid) && name.startsWith("refs/"))
+            refs.set(name, oid);
+    }
+    return refs;
+}
+/** Capabilities from the ref advertisement's first NUL-delimited capability list. */
+export function advertisedCapabilities(body) {
+    for (const raw of readPacketLines(body, false)) {
+        const line = decoder.decode(raw);
+        const separator = line.indexOf("\0");
+        if (separator >= 0)
+            return new Set(line
+                .slice(separator + 1)
+                .trim()
+                .split(" ")
+                .filter(Boolean));
+    }
+    return new Set();
+}

package/dist/git.d.ts

@@ -0,0 +1,322 @@
+import { gitRepositoryNameSchema } from "@fungi.computer/puffball/git-representation";
+import * as z from "zod";
+import { type HostActor, type WorkflowAttestation } from "@fungi.computer/puffball/app-method-runtime";
+/** Requested installation-scoped Git authority; a declaration is never a grant. */
+export declare const gitRepositoryCapability = "git.repository";
+/** Local repository name decoded at a host's repository boundary. */
+export type GitRepositoryName = z.output<typeof gitRepositoryNameSchema>;
+/**
+ * Host-selected repository namespace. Team identity comes from the host;
+ * decoding this reference never grants access to either namespace.
+ */
+export declare const repositoryRefSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"installation">;
+    installationId: z.ZodString;
+    repository: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"team-source">;
+    repository: z.ZodString;
+}, z.core.$strict>], "kind">;
+/** Installation-local repository or registered Team source, selected by its host. */
+export type RepositoryRef = z.output<typeof repositoryRefSchema>;
+/** Stable namespace identity, serialized through the canonical repository decoder. */
+export declare function repositoryRefKey(repository: RepositoryRef): string;
+/** Compare repository namespace and coordinates independently of allocation or property order. */
+export declare function repositoryRefsEqual(left: RepositoryRef, right: RepositoryRef): boolean;
+/** Host-held writer identity; Workflow attribution reuses Puffball's sole grammar. */
+export type GitWriter = Readonly<{
+    kind: "actor";
+    actor: HostActor;
+    role?: "owner" | "member";
+    workflow?: WorkflowAttestation & {
+        branches: readonly string[];
+    };
+}> | Readonly<{
+    kind: "installation";
+    installationId: string;
+    onBehalfOf: HostActor | null;
+}>;
+/** Canonical Git writer decoder; identity is attested by a host, never by an App. */
+export declare const gitWriterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"actor">;
+    actor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"member">;
+        memberId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"agent">;
+        agentId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+        keyId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strict>], "kind">;
+    role: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniEnum<{
+        member: "member";
+        owner: "owner";
+    }>>;
+    workflow: z.ZodOptional<z.ZodObject<{
+        armedBy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"member">;
+            memberId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"agent">;
+            agentId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+            keyId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>], "kind">;
+        branches: z.ZodArray<z.ZodString>;
+        workflowId: import("zod/mini").ZodMiniString<string>;
+        runId: import("zod/mini").ZodMiniString<string>;
+        nodeId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"installation">;
+    installationId: z.ZodString;
+    onBehalfOf: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"member">;
+        memberId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"agent">;
+        agentId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+        keyId: import("zod/mini").ZodMiniString<string>;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>], "kind">;
+/** The App's question covers the whole push, under host-held attribution. */
+export declare const gitPushQuestionSchema: z.ZodObject<{
+    repository: z.ZodString;
+    writer: z.ZodObject<{
+        kind: z.ZodLiteral<"actor">;
+        actor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"member">;
+            memberId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"agent">;
+            agentId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+            keyId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>], "kind">;
+        role: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniEnum<{
+            member: "member";
+            owner: "owner";
+        }>>;
+        workflow: z.ZodOptional<z.ZodObject<{
+            armedBy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: import("zod/mini").ZodMiniLiteral<"member">;
+                memberId: import("zod/mini").ZodMiniString<string>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: import("zod/mini").ZodMiniLiteral<"agent">;
+                agentId: import("zod/mini").ZodMiniString<string>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+                keyId: import("zod/mini").ZodMiniString<string>;
+            }, z.core.$strict>], "kind">;
+            branches: z.ZodArray<z.ZodString>;
+            workflowId: import("zod/mini").ZodMiniString<string>;
+            runId: import("zod/mini").ZodMiniString<string>;
+            nodeId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    updates: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        before: z.ZodString;
+        after: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** A whole push verdict; refusal messages are shown by ordinary Git clients. */
+export declare const gitPushVerdictSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    allowed: z.ZodLiteral<true>;
+}, z.core.$strict>, z.ZodObject<{
+    allowed: z.ZodLiteral<false>;
+    refused: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "allowed">;
+/** Ref question sent only after host grant and Workflow branch admission. */
+export type GitPushQuestion = z.output<typeof gitPushQuestionSchema>;
+/** Explicit permission or bounded per-ref refusal for the whole push. */
+export type GitPushVerdict = z.output<typeof gitPushVerdictSchema>;
+/** One accepted push, with host attribution and no remote or credential. */
+export declare const appGitPushFactSchema: z.ZodObject<{
+    repository: z.ZodString;
+    writer: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"actor">;
+        actor: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"member">;
+            memberId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"agent">;
+            agentId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+            keyId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>], "kind">;
+        role: import("zod/mini").ZodMiniOptional<import("zod/mini").ZodMiniEnum<{
+            member: "member";
+            owner: "owner";
+        }>>;
+        workflow: z.ZodOptional<z.ZodObject<{
+            armedBy: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: import("zod/mini").ZodMiniLiteral<"member">;
+                memberId: import("zod/mini").ZodMiniString<string>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: import("zod/mini").ZodMiniLiteral<"agent">;
+                agentId: import("zod/mini").ZodMiniString<string>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+                keyId: import("zod/mini").ZodMiniString<string>;
+            }, z.core.$strict>], "kind">;
+            branches: z.ZodArray<z.ZodString>;
+            workflowId: import("zod/mini").ZodMiniString<string>;
+            runId: import("zod/mini").ZodMiniString<string>;
+            nodeId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"installation">;
+        installationId: z.ZodString;
+        onBehalfOf: z.ZodNullable<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"member">;
+            memberId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"agent">;
+            agentId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: import("zod/mini").ZodMiniLiteral<"team-key">;
+            keyId: import("zod/mini").ZodMiniString<string>;
+        }, z.core.$strict>], "kind">>;
+    }, z.core.$strict>], "kind">;
+    updates: z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        before: z.ZodString;
+        after: z.ZodString;
+    }, z.core.$strict>>;
+    unexplained: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        journaled: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>;
+    eventId: z.ZodString;
+}, z.core.$strict>;
+/** One bounded ref update, shared by push questions and accepted facts. */
+export type GitRefUpdate = z.output<typeof appGitPushFactSchema>["updates"][number];
+/** Host-delivered push fact; retries retain the same event ID. */
+export type AppGitPushFact = z.output<typeof appGitPushFactSchema>;
+/** App-owned lifecycle handler, separate from its callable method catalog. */
+export type AppGitLifecycle = Readonly<{
+    /** An absent authorization handler refuses external pushes. */
+    authorizeGitPush?: (question: GitPushQuestion) => Promise<GitPushVerdict>;
+    /** Handle an accepted push; persist eventId with the effects to make retries idempotent. */
+    onGitPush?: (fact: AppGitPushFact) => Promise<void>;
+}>;
+/** Parse a host-admitted fact and invoke its lifecycle handler, preserving rejection. */
+export declare function dispatchAppGitPush(lifecycle: AppGitLifecycle, raw: unknown): Promise<void>;
+/** Credential-free repository metadata, with installation-local names. */
+export type GitRepositoryInfo = Readonly<{
+    /** Local repository name. */
+    name: string;
+    /** Default branch, without the refs/heads prefix. */
+    defaultBranch: string;
+    /** ISO timestamp of the last push, or null before the first push. */
+    lastPushAt: string | null;
+    /** Local fork source, or null for a newly created repository. */
+    source: string | null;
+}>;
+/** Artifacts commit metadata, with the provider's credential fields absent. */
+export type GitCommit = Readonly<{
+    /** SHA-1 commit ID. */
+    hash: string;
+    /** SHA-1 root tree ID. */
+    treeHash: string;
+    /** Commit message. */
+    message: string;
+    /** Author identity recorded in the commit. */
+    author: {
+        name: string;
+        email: string;
+    };
+    /** Committer identity recorded in the commit. */
+    committer: {
+        name: string;
+        email: string;
+    };
+    /** Parent commit IDs, in Git order. */
+    parents: string[];
+    /** Author timestamp, in Unix seconds. */
+    authoredAt: number;
+    /** Committer timestamp, in Unix seconds. */
+    committedAt: number;
+}>;
+/** One immediate child of a Git tree. */
+export type GitTreeEntry = Readonly<{
+    /** Name relative to the tree. */
+    name: string;
+    /** Canonical Git mode. */
+    mode: string;
+    /** SHA-1 object ID. */
+    hash: string;
+    /** Git object type; executable and symlink entries are blobs distinguished by mode. */
+    type: "blob" | "tree" | "commit";
+}>;
+/** Smart-HTTP request; the host supplies and keeps the provider credential. */
+export type GitExchangeRequest = Readonly<{
+    /** Git upload-pack (read) or receive-pack (write). */
+    service: "upload-pack" | "receive-pack";
+    /** Advertisement or data exchange phase. */
+    phase: "advertise" | "exchange";
+    /** Request bytes for exchange, or null for advertisement; bounded by the host. */
+    body: Uint8Array | null;
+    /** Protocol headers; the host never trusts incoming authorization headers. */
+    headers: Readonly<Record<string, string>>;
+}>;
+/** Credential-free RPC response; host adapters own stream conversion and byte bounds. */
+export type GitExchangeResponse = Readonly<{
+    /** Provider HTTP status. */
+    status: number;
+    /** Protocol response headers, without host credentials. */
+    headers: Readonly<Record<string, string>>;
+    /** Git protocol response bytes. */
+    body: Uint8Array;
+}>;
+/** Installation-scoped GIT backend binding; approved operations and actor grants bound every call. */
+export type GitBinding = Readonly<{
+    /** Create a repository in this installation. */
+    create(name: string, options?: {
+        description?: string;
+        defaultBranch?: string;
+    }): Promise<GitRepositoryInfo>;
+    /**
+     * Fork another repository in this installation, waiting for it to serve
+     * reads. When `target` already exists the host answers with that
+     * repository instead; callers compare its `source` before adopting it.
+     */
+    fork(source: string, target: string, options?: {
+        description?: string;
+    }): Promise<GitRepositoryInfo>;
+    /** Return the host-issued clone URL for this installation repository; authentication stays with the host. */
+    cloneUrl(name: string): Promise<string>;
+    /** Read repository metadata, or null when missing. */
+    info(name: string): Promise<GitRepositoryInfo | null>;
+    /** Delete a repository in this installation. */
+    delete(name: string): Promise<boolean>;
+    /** Read first-parent history, newest first. */
+    log(name: string, options: {
+        ref: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<GitCommit[]>;
+    /** Read commit metadata, or null when missing. */
+    readCommit(name: string, hash: string): Promise<GitCommit | null>;
+    /** Read tree children, or null when missing. */
+    readTree(name: string, hash: string): Promise<GitTreeEntry[] | null>;
+    /** Read a blob bounded to 32 MiB, or null when missing. */
+    readBlob(name: string, hash: string): Promise<Uint8Array | null>;
+    /** Read advertised ref names and object IDs. */
+    refs(name: string): Promise<{
+        name: string;
+        hash: string;
+    }[]>;
+    /** Exchange Git bytes; receive-pack requires both exchange and write approval. */
+    exchange(name: string, request: GitExchangeRequest): Promise<GitExchangeResponse>;
+}>;