@crowdedkingdoms/crowdyjs 16.2.0 → 17.0.0-dev.1

package/dist/domains/crowdyStudio.js

@@ -1,17 +1,29 @@
+import { CrowdyStudioGitHubTransport, } from '../crowdy-studio/github/transport.js';
+import { studioFileToRepoPath } from '../crowdy-studio/github/layout.js';
 import { CrowdyGraphQLError, CrowdyHttpError, CrowdyNetworkError, CrowdyTimeoutError, } from '../errors.js';
 import { CrowdyStudioOfflineError, CrowdyStudioRevisionConflictError, normalizeCrowdyStudioPath, } from '../crowdy-studio/models.js';
-import { CrowdyStudioCommonFilesDocument, CrowdyStudioImportSource, CrowdyStudioLibraryFilesDocument, CrowdyStudioLibrarySaveDocument, CrowdyStudioPairingPreference as CrowdyStudioPairingPreferenceEnum, CrowdyStudioProjectCreateDocument, CrowdyStudioProjectDocument, CrowdyStudioProjectImportFileDocument, CrowdyStudioProjectSaveDocument, CrowdyStudioProjectsDocument, } from '../generated/graphql.js';
+import { CrowdyStudioCommonFilesDocument, CrowdyStudioImportSource, CrowdyStudioLibraryFilesDocument, CrowdyStudioLibrarySaveDocument, CrowdyStudioPairingPreference as CrowdyStudioPairingPreferenceEnum, CrowdyStudioProjectSource as CrowdyStudioProjectSourceEnum, CrowdyStudioProjectCreateDocument, CrowdyStudioProjectDocument, CrowdyStudioProjectImportFileDocument, CrowdyStudioProjectSaveDocument, CrowdyStudioProjectsDocument, } from '../generated/graphql.js';
 /**
  * Schema-coupled Game API adapter for private Crowdy Studio projects and
  * reusable files. Generated GraphQL documents and DTOs stay in this module;
- * the controller and public project models remain transport-neutral. Mutable
- * projects remain separate from immutable player-compute versions, and only
- * the controller's deploy path converts target files to sourceFilesJson.
+ * the controller and public project models remain transport-neutral.
+ *
+ * A project's `source` decides how {@link saveProject} persists files:
+ * `STUDIO` projects go through `crowdyStudioProjectSave` under the project
+ * revision; `GITHUB` projects commit each changed file through
+ * `crowdyStudioGitHubPutFile` / `DeleteFile` under `github.sha`
+ * (`expectedCommitSha`), because their files are a server-maintained mirror
+ * of the repository and the Studio file mutations refuse them. Either way a
+ * lost race is a {@link CrowdyStudioRevisionConflictError} and the editor's
+ * "the remote moved" recovery applies. The controller never learns which.
  */
 export class CrowdyStudioAPI {
     constructor(graphql) {
         this.graphql = graphql;
         this.baselines = new Map();
+        /** Layout per `projectId@commit`; commits are immutable so this never goes stale. */
+        this.layouts = new Map();
+        this.github = new CrowdyStudioGitHubTransport(graphql);
     }
     async listProjects(scope) {
         const data = await this.request(CrowdyStudioProjectsDocument, {
@@ -47,13 +59,16 @@ export class CrowdyStudioAPI {
         return this.remember(fromProjectDto(data.crowdyStudioProjectCreate, input.gridId));
     }
     async saveProject(input) {
+        const baseline = this.baselines.get(input.projectId) ??
+            (await this.getProject({
+                appId: input.appId,
+                gridId: input.gridId,
+                projectId: input.projectId,
+            }));
+        if (baseline.source === 'GITHUB' && baseline.github?.sha) {
+            return this.saveBoundProject(baseline, input);
+        }
         try {
-            const baseline = this.baselines.get(input.projectId) ??
-                (await this.getProject({
-                    appId: input.appId,
-                    gridId: input.gridId,
-                    projectId: input.projectId,
-                }));
             const delta = projectFileDelta(baseline, input);
             const data = await this.request(CrowdyStudioProjectSaveDocument, {
                 input: {
@@ -104,6 +119,114 @@ export class CrowdyStudioAPI {
             throw error;
         }
     }
+    /**
+     * Persist a GITHUB project: metadata through the project save (a CAS on the
+     * revision, no file bodies), then each changed file as its own commit on the
+     * bound branch, each carrying the commit the previous one produced. A file
+     * put is atomic on the server (GitHub commit, then mirror + `github_sha`
+     * advance in one transaction), so a stale race part-way through leaves the
+     * earlier commits on the branch and this project describing them; the
+     * conflict recovery re-reads and the remaining diffs are re-applied against
+     * the new commit. Layout comes from the API at the commit being written to.
+     */
+    async saveBoundProject(baseline, input) {
+        const scope = { appId: input.appId, projectId: input.projectId };
+        const startSha = baseline.github?.sha;
+        if (!startSha) {
+            throw new Error('The bound project has no mirror commit; refresh it from GitHub first.');
+        }
+        try {
+            if (metadataChanged(baseline, input)) {
+                await this.request(CrowdyStudioProjectSaveDocument, {
+                    input: {
+                        appId: input.appId,
+                        projectId: input.projectId,
+                        expectedRevision: input.expectedRevisionId,
+                        gridId: input.gridId,
+                        name: input.metadata.name,
+                        description: input.metadata.description ?? null,
+                        serverModuleName: input.metadata.serverModuleName ?? null,
+                        clientModuleName: input.metadata.clientModuleName ?? null,
+                        pairingPreference: toApiPairing(projectKind(input), input.metadata.pairingPreference),
+                        upserts: [],
+                        deletes: [],
+                    },
+                });
+            }
+            const delta = projectFileDelta(baseline, input);
+            let sha = startSha;
+            if (delta.upserts.length > 0 || delta.deletes.length > 0) {
+                const layout = await this.layoutAt(scope, sha);
+                for (const file of delta.upserts) {
+                    const path = normalizeCrowdyStudioPath(file.path);
+                    const repoPath = studioFileToRepoPath(layout, file.target, path);
+                    if (!repoPath) {
+                        throw new Error(`The bound repository's crowdy.json has no ${file.target.toLowerCase()} directory, so ${path} has nowhere to go.`);
+                    }
+                    const written = await this.github.putFile({
+                        ...scope,
+                        path: repoPath,
+                        content: file.content,
+                        message: `studio: update ${repoPath}`,
+                        expectedCommitSha: sha,
+                    });
+                    sha = written.commitSha ?? sha;
+                }
+                for (const file of delta.deletes) {
+                    const repoPath = studioFileToRepoPath(layout, file.target, normalizeCrowdyStudioPath(file.path));
+                    if (!repoPath)
+                        continue;
+                    const status = await this.github.deleteFile({
+                        ...scope,
+                        path: repoPath,
+                        message: `studio: delete ${repoPath}`,
+                        expectedCommitSha: sha,
+                    });
+                    sha = status.githubSha ?? sha;
+                }
+            }
+            return await this.getProject({
+                appId: input.appId,
+                gridId: input.gridId,
+                projectId: input.projectId,
+            });
+        }
+        catch (error) {
+            if (error instanceof CrowdyGraphQLError &&
+                (error.code === 'GITHUB_STALE_SHA' ||
+                    error.code === 'CROWDY_STUDIO_REVISION_CONFLICT' ||
+                    error.message.includes('GITHUB_STALE_SHA') ||
+                    error.message.includes('CROWDY_STUDIO_REVISION_CONFLICT'))) {
+                let remoteProject;
+                try {
+                    remoteProject = await this.getProject({
+                        appId: input.appId,
+                        gridId: input.gridId,
+                        projectId: input.projectId,
+                    });
+                }
+                catch {
+                    // The conflict remains actionable if the follow-up read fails.
+                }
+                throw new CrowdyStudioRevisionConflictError(error.message, remoteProject);
+            }
+            throw error;
+        }
+    }
+    async layoutAt(scope, commitSha) {
+        const key = `${scope.projectId}@${commitSha}`;
+        const cached = this.layouts.get(key);
+        if (cached)
+            return cached;
+        const layout = await this.github.layout({ ...scope, commitSha });
+        if (this.layouts.size > 64) {
+            const [oldest] = this.layouts.keys();
+            if (oldest !== undefined)
+                this.layouts.delete(oldest);
+        }
+        this.layouts.set(key, layout);
+        return layout;
+    }
     async listPersonalLibraryFiles(scope) {
         const data = await this.request(CrowdyStudioLibraryFilesDocument, {
             appId: scope.appId,
@@ -172,11 +295,18 @@ export class CrowdyStudioAPI {
     }
 }
 function fromSummaryDto(dto) {
+    const bound = dto.source === CrowdyStudioProjectSourceEnum.Github &&
+        dto.githubOwner &&
+        dto.githubRepo &&
+        dto.githubBranch;
     return {
         projectId: dto.projectId,
         name: dto.name,
         kind: kindFromApi(dto.pairingPreference),
         revisionId: String(dto.revision),
+        source: bound ? 'GITHUB' : 'STUDIO',
+        ...(bound ? { github: `${dto.githubOwner}/${dto.githubRepo}@${dto.githubBranch}` } : {}),
+        githubSha: bound ? (dto.githubSha ?? null) : null,
         ...(dto.serverModuleName
             ? { serverModuleName: dto.serverModuleName }
             : {}),
@@ -215,6 +345,18 @@ function fromProjectDto(dto, fallbackGridId) {
             id: String(dto.revision),
             savedAt: dto.updatedAt,
         },
+        source: dto.source === CrowdyStudioProjectSourceEnum.Github ? 'GITHUB' : 'STUDIO',
+        github: dto.source === CrowdyStudioProjectSourceEnum.Github &&
+            dto.githubOwner &&
+            dto.githubRepo &&
+            dto.githubBranch
+            ? {
+                owner: dto.githubOwner,
+                repo: dto.githubRepo,
+                branch: dto.githubBranch,
+                sha: dto.githubSha ?? null,
+            }
+            : null,
         createdAt: dto.createdAt,
         updatedAt: dto.updatedAt,
     };
@@ -282,6 +424,17 @@ function projectKind(input) {
         return 'SERVER';
     return 'CLIENT';
 }
+function metadataChanged(baseline, input) {
+    const a = baseline.metadata;
+    const b = input.metadata;
+    return (baseline.gridId !== input.gridId ||
+        a.name !== b.name ||
+        (a.description ?? '') !== (b.description ?? '') ||
+        (a.serverModuleName ?? '') !== (b.serverModuleName ?? '') ||
+        (a.clientModuleName ?? '') !== (b.clientModuleName ?? '') ||
+        toApiPairing(baseline.kind, a.pairingPreference) !==
+            toApiPairing(projectKind(input), b.pairingPreference));
+}
 function projectFileDelta(baseline, input) {
     const previous = new Map(baseline.files.map((file) => [
         `${file.target}:${normalizeCrowdyStudioPath(file.path)}`,
@@ -306,5 +459,6 @@ function cloneProject(project) {
         metadata: { ...project.metadata },
         files: project.files.map((file) => ({ ...file })),
         revision: { ...project.revision },
+        github: project.github ? { ...project.github } : null,
     };
 }

package/dist/generated/graphql.d.ts

@@ -1521,6 +1521,8 @@ export type BillingWriteOff = {
 export type BindCrowdyStudioGitHubInput = {
     appId: Scalars['BigInt']['input'];
     branch?: InputMaybe<Scalars['String']['input']>;
+    /** Which side is the truth for the first commit. */
+    initial: CrowdyStudioGitHubBindInitial;
     owner: Scalars['String']['input'];
     projectId: Scalars['String']['input'];
     repo: Scalars['String']['input'];
@@ -3066,13 +3068,38 @@ export declare enum CrowdyStudioFileProvenance {
     /** The file was copied from a specific revision of the owner’s private personal library. */
     Library = "LIBRARY"
 }
+export type CrowdyStudioGitHubAtCommitInput = {
+    appId: Scalars['BigInt']['input'];
+    /** Full 40-hex commit to read at. Omitted reads the project githubSha (the mirror commit), never the branch head. */
+    commitSha?: InputMaybe<Scalars['String']['input']>;
+    projectId: Scalars['String']['input'];
+};
+/** What the first commit of a bind does. The repository and the Studio project cannot both be the truth on day one, so the owner says which one is. */
+export declare enum CrowdyStudioGitHubBindInitial {
+    /** The Studio project files are committed to the branch (with a crowdy.json when the repository has none). Refused with GITHUB_REPO_HAS_FILES when the repository already carries rust under the layout roots. */
+    PushProject = "PUSH_PROJECT",
+    /** The repository is adopted as it is; the Studio project files are replaced by the rust under the layout roots at branch HEAD. Refused with GITHUB_REPO_EMPTY when there is nothing to take. */
+    TakeRepository = "TAKE_REPOSITORY"
+}
 export type CrowdyStudioGitHubConnectStart = {
     __typename?: 'CrowdyStudioGitHubConnectStart';
     /** Install URL for this tier's App, carrying a signed state. */
     connectUrl: Scalars['String']['output'];
 };
+export type CrowdyStudioGitHubDeleteFileInput = {
+    appId: Scalars['BigInt']['input'];
+    /** The project githubSha the writer read; stale is refused with GITHUB_STALE_SHA. */
+    expectedCommitSha: Scalars['String']['input'];
+    message: Scalars['String']['input'];
+    path: Scalars['String']['input'];
+    projectId: Scalars['String']['input'];
+    /** Blob SHA of the file being deleted. Optional; resolved from the tree at expectedCommitSha. */
+    sha?: InputMaybe<Scalars['String']['input']>;
+};
 export type CrowdyStudioGitHubFile = {
     __typename?: 'CrowdyStudioGitHubFile';
+    /** Commit the file was read at, or the commit a write created. After a write this is the new project githubSha. */
+    commitSha: Maybe<Scalars['String']['output']>;
     /** UTF-8 content. */
     content: Scalars['String']['output'];
     path: Scalars['String']['output'];
@@ -3081,9 +3108,25 @@ export type CrowdyStudioGitHubFile = {
 };
 export type CrowdyStudioGitHubFileInput = {
     appId: Scalars['BigInt']['input'];
+    /** Full 40-hex commit to read at. Omitted reads the project githubSha (the mirror commit), never the branch head. */
+    commitSha?: InputMaybe<Scalars['String']['input']>;
     path: Scalars['String']['input'];
     projectId: Scalars['String']['input'];
 };
+/** Where the SERVER and CLIENT crates live in the bound repository, resolved from crowdy.json (or inferred) at one commit. The only layout grammar: clients must not parse crowdy.json themselves. */
+export type CrowdyStudioGitHubLayout = {
+    __typename?: 'CrowdyStudioGitHubLayout';
+    /** Prefix visitors may fetch assets from (no trailing slash). */
+    assets: Scalars['String']['output'];
+    /** Directory of the CLIENT Cargo.toml, or null when server-only. */
+    client: Maybe<Scalars['String']['output']>;
+    /** Commit the layout was resolved at. */
+    commitSha: Scalars['String']['output'];
+    /** A crowdy.json exists at the repository root. False means the layout was inferred from the tree. */
+    fromFile: Scalars['Boolean']['output'];
+    /** Directory of the SERVER Cargo.toml; `.` is the repository root. */
+    server: Scalars['String']['output'];
+};
 export type CrowdyStudioGitHubProjectInput = {
     appId: Scalars['BigInt']['input'];
     projectId: Scalars['String']['input'];
@@ -3091,10 +3134,12 @@ export type CrowdyStudioGitHubProjectInput = {
 export type CrowdyStudioGitHubPutFileInput = {
     appId: Scalars['BigInt']['input'];
     content: Scalars['String']['input'];
+    /** The project githubSha the writer read. The write is refused with GITHUB_STALE_SHA when the project has moved on, so two editors cannot silently interleave. */
+    expectedCommitSha: Scalars['String']['input'];
     message: Scalars['String']['input'];
     path: Scalars['String']['input'];
     projectId: Scalars['String']['input'];
-    /** Required when the file already exists. */
+    /** Blob SHA of the file being replaced. Optional: the server resolves it from the tree at expectedCommitSha, which is the lock that matters. When sent it must agree with that tree. */
     sha?: InputMaybe<Scalars['String']['input']>;
 };
 export type CrowdyStudioGitHubRepo = {
@@ -3112,19 +3157,26 @@ export type CrowdyStudioGitHubStatus = {
     accountLogin: Maybe<Scalars['String']['output']>;
     /** `User` or `Organization`. */
     accountType: Maybe<Scalars['String']['output']>;
-    /** Studio autosave also pushes to the bound repository. Off by default; the project owner opts in. */
-    autosave: Scalars['Boolean']['output'];
     branch: Maybe<Scalars['String']['output']>;
     /** This tier has a GitHub App registered. */
     configured: Scalars['Boolean']['output'];
     /** The caller has installed the App on a GitHub account. */
     connected: Scalars['Boolean']['output'];
+    /** Commit the project mirror is at. Every bound write presents it as expectedCommitSha; a stale value is refused with GITHUB_STALE_SHA. Null when the project is not bound. */
+    githubSha: Maybe<Scalars['String']['output']>;
     /** Where to send the modder to install or manage the App. */
     installUrl: Maybe<Scalars['String']['output']>;
     /** Bound repository owner, when a project was named. */
     owner: Maybe<Scalars['String']['output']>;
     repo: Maybe<Scalars['String']['output']>;
 };
+/** Recursive listing of the bound repository at one commit. The commit is the one the paths were read at, so a follow-up file read can pin it. */
+export type CrowdyStudioGitHubTree = {
+    __typename?: 'CrowdyStudioGitHubTree';
+    /** Commit the tree was read at. */
+    commitSha: Scalars['String']['output'];
+    entries: Array<CrowdyStudioGitHubTreeEntry>;
+};
 export type CrowdyStudioGitHubTreeEntry = {
     __typename?: 'CrowdyStudioGitHubTreeEntry';
     /** Repo-relative path. */
@@ -3228,8 +3280,16 @@ export type CrowdyStudioProject = {
     description: Maybe<Scalars['String']['output']>;
     /** Total file count across both targets; each target is independently capped at eight. */
     fileCount: Scalars['Int']['output'];
-    /** Private project files ordered by target and path. Bounded to eight files per target. */
+    /** Private project files ordered by target and path. Bounded to eight files per target. For a GITHUB project this is the mirror of the repository at githubSha, read the same way. */
     files: Array<CrowdyStudioProjectFile>;
+    /** Bound branch. */
+    githubBranch: Maybe<Scalars['String']['output']>;
+    /** Bound repository owner, or null for a STUDIO project. */
+    githubOwner: Maybe<Scalars['String']['output']>;
+    /** Bound repository name. */
+    githubRepo: Maybe<Scalars['String']['output']>;
+    /** Commit the mirror is at. Present it as expectedCommitSha on every bound write; a stale value is refused with GITHUB_STALE_SHA. */
+    githubSha: Maybe<Scalars['String']['output']>;
     /** Optional grid affinity. It survives a grid transfer and does not itself grant deploy authority. */
     gridId: Maybe<Scalars['BigInt']['output']>;
     /** Player-facing project name. */
@@ -3246,6 +3306,8 @@ export type CrowdyStudioProject = {
     sdkVersion: Scalars['String']['output'];
     /** Stable crate-style SERVER module name used when the owner chooses to deploy, or null when unassigned. */
     serverModuleName: Maybe<Scalars['String']['output']>;
+    /** STUDIO until the owner binds a repository; GITHUB while one is bound. Decides which mutations may write files. */
+    source: CrowdyStudioProjectSource;
     /** Total UTF-8 source bytes across both targets, bounded by target and aggregate owner quotas. */
     totalBytes: Scalars['BigInt']['output'];
     /** Timestamp of the latest successful project mutation. */
@@ -3291,6 +3353,13 @@ export type CrowdyStudioProjectFileInput = {
     /** Project target receiving this file. */
     target: CrowdyStudioTarget;
 };
+/** Where a project’s files are authored. Every project starts as STUDIO; its owner may bind a GitHub repository later (crowdyStudioGitHubBind) and unbind it again. GitHub is never required. */
+export declare enum CrowdyStudioProjectSource {
+    /** The bound repository is the working tree. `files` is a server-maintained mirror of the rust under the layout roots at githubSha; writes go through crowdyStudioGitHubPutFile / DeleteFile with expectedCommitSha, and the Studio file mutations refuse with GITHUB_BOUND_USE_CONTENTS. */
+    Github = "GITHUB",
+    /** Files live in Crowdy Studio and are written with the crowdyStudioProject* file mutations under the project revision. */
+    Studio = "STUDIO"
+}
 /** Whether this player has accepted that their Crowdy Studio project source may be sent to a model provider (under the platform ZDR / no-collection routing) for this app. */
 export type CrowdyStudioProviderConsent = {
     __typename?: 'CrowdyStudioProviderConsent';
@@ -3359,24 +3428,23 @@ export type DeployComputeVersionInput = {
     /** JSON object mapping relative paths to file contents. Must include Cargo.toml and src/lib.rs; only .rs files under src/ plus Cargo.toml are allowed. Dependencies are restricted to the platform crate allowlist; build.rs and [build-dependencies] are rejected. */
     sourceFilesJson: Scalars['String']['input'];
 };
+/** Deploy one target of a Crowdy Studio project the caller owns. The server resolves the source itself — the project files at their saved revision for a STUDIO project, the rust under the layout roots at commitSha (default githubSha) for a GITHUB project — so a client never uploads file bodies and what compiles is exactly what was saved or committed. */
 export type DeployPlayerComputeInput = {
-    /** Guest ABI version. P1 supports ABI 0. */
-    abiVersion?: InputMaybe<Scalars['Int']['input']>;
     /** App containing the owned grid. */
     appId: Scalars['BigInt']['input'];
+    /** GITHUB projects only: the full 40-hex commit to compile. Defaults to the project githubSha (the mirror commit). Refused for a STUDIO project. */
+    commitSha?: InputMaybe<Scalars['String']['input']>;
     /** Optional player-facing module description. */
     description?: InputMaybe<Scalars['String']['input']>;
     /** Deploy in draft mode (live-coding iteration): the module runs for its author but its spatial egress is suppressed server-side, so no other session in the grid observes its world effects. Omit or false for a normal deploy. */
     draft?: InputMaybe<Scalars['Boolean']['input']>;
     /** Owned grid that confines server execution. */
     gridId: Scalars['BigInt']['input'];
-    /** Lowercase crate-style module name, unique within the grid. */
-    name: Scalars['String']['input'];
-    /** Pinned crowdy-compute-sdk version. Defaults to 0.1.5. */
-    sdkVersion?: InputMaybe<Scalars['String']['input']>;
-    /** JSON object mapping Cargo.toml and src/*.rs relative paths to source. P1 player caps: at most 8 files, 64 KiB/file, 256 KiB total. */
-    sourceFilesJson: Scalars['String']['input'];
-    /** SERVER or CLIENT compile target. */
+    /** Lowercase crate-style module name, unique within the grid. Defaults to the project’s module name for the target and must equal it when both are set. */
+    name?: InputMaybe<Scalars['String']['input']>;
+    /** Crowdy Studio project (owned by the caller, in this app) whose target is deployed. */
+    projectId: Scalars['String']['input'];
+    /** SERVER or CLIENT compile target; the project must have files for it. */
     target: PlayerComputeTarget;
     /** Optional server tick rate in Hz. Omit for invoke/event-only modules or CLIENT artifacts. Clamped by the effective player/app policy. */
     tickHz?: InputMaybe<Scalars['Float']['input']>;
@@ -5071,15 +5139,17 @@ export type Mutation = {
     creditOrgWallet: WalletTransaction;
     /** Publish a new immutable version of an app-scoped Crowdy Studio-curated common file and make it the current player-readable version. Requires an app-scoped token plus the app manage_compute permission. Old versions remain immutable for provenance; an idempotency key is strongly recommended for transport retries. */
     crowdyStudioCommonPublish: CrowdyStudioCommonFile;
-    /** Bind a Crowdy Studio project you own to a repository granted to your installation. Verifies the branch exists. Identity session only. Autosave stays off until you turn it on. */
+    /** Bind a Crowdy Studio project you own to a repository granted to your installation, and make the two agree in one commit: PUSH_PROJECT commits the project files to the branch (refused with GITHUB_REPO_HAS_FILES when the branch already has rust under the layout roots); TAKE_REPOSITORY replaces the project files with the rust on the branch (refused with GITHUB_REPO_EMPTY when there is none). From then on the repository is the working tree and the project files are a mirror of it at githubSha. Identity session only. */
     crowdyStudioGitHubBind: CrowdyStudioGitHubStatus;
     /** Install URL for this tier's Crowdy Studio GitHub App with a signed state. Identity session only. No GitHub token ever reaches the browser. */
     crowdyStudioGitHubConnectUrl: CrowdyStudioGitHubConnectStart;
-    /** Create or update one UTF-8 file in the bound repository. Send the current sha on update; a stale sha is refused with GITHUB_STALE_SHA. */
+    /** Delete one file from the bound repository as a commit on the bound branch, under the same blob-sha and expectedCommitSha guards as crowdyStudioGitHubPutFile. A project file leaves the mirror with it. crowdy.json cannot be deleted this way. */
+    crowdyStudioGitHubDeleteFile: CrowdyStudioGitHubStatus;
+    /** Create or update one UTF-8 file in the bound repository as a commit on the bound branch. Send the blob sha on update and the project githubSha as expectedCommitSha; either being stale is refused with GITHUB_STALE_SHA and nothing moves. When the path is a project file under the layout roots the project mirror advances with it; the returned commitSha is the new githubSha. */
     crowdyStudioGitHubPutFile: CrowdyStudioGitHubFile;
-    /** Opt a bound project into (or out of) pushing Studio autosaves to GitHub. Default is off. */
-    crowdyStudioGitHubSetAutosave: CrowdyStudioGitHubStatus;
-    /** Remove the repository bind from a project you own. Files in Crowdy Studio are untouched. */
+    /** Bring the project mirror forward to the branch head. This is how a push made outside Crowdy Studio reaches the editor and the agent; githubSha becomes the head commit. A no-op when already at head. */
+    crowdyStudioGitHubRefresh: CrowdyStudioGitHubStatus;
+    /** Remove the repository bind from a project you own. The project keeps its files (the mirror at githubSha) and is a plain Crowdy Studio project again; nothing on GitHub changes. Identity session only. */
     crowdyStudioGitHubUnbind: CrowdyStudioGitHubStatus;
     /** Create or optimistically update one private personal-library source file. Requires an app-scoped token; ownership is always the authenticated player and cannot be delegated. Safe source paths, 64-KiB content, revision, and configurable bounded aggregate library storage are enforced atomically. */
     crowdyStudioLibrarySave: CrowdyStudioLibraryFile;
@@ -5619,11 +5689,14 @@ export type MutationCrowdyStudioCommonPublishArgs = {
 export type MutationCrowdyStudioGitHubBindArgs = {
     input: BindCrowdyStudioGitHubInput;
 };
+export type MutationCrowdyStudioGitHubDeleteFileArgs = {
+    input: CrowdyStudioGitHubDeleteFileInput;
+};
 export type MutationCrowdyStudioGitHubPutFileArgs = {
     input: CrowdyStudioGitHubPutFileInput;
 };
-export type MutationCrowdyStudioGitHubSetAutosaveArgs = {
-    input: SetCrowdyStudioGitHubAutosaveInput;
+export type MutationCrowdyStudioGitHubRefreshArgs = {
+    input: CrowdyStudioGitHubProjectInput;
 };
 export type MutationCrowdyStudioGitHubUnbindArgs = {
     input: CrowdyStudioGitHubProjectInput;
@@ -7294,12 +7367,18 @@ export type PlayerWasmModuleVersion = {
     compiledSizeBytes: Maybe<Scalars['BigInt']['output']>;
     /** Version creation time. */
     createdAt: Scalars['DateTime']['output'];
+    /** Commit the rust was fetched at (GITHUB projects). A force-push of the bound branch never changes what this version runs. */
+    githubCommitSha: Maybe<Scalars['String']['output']>;
     /** Parent module UUID. */
     moduleId: Scalars['String']['output'];
     /** Whether anyone may read this immutable version source. */
     openSource: Scalars['Boolean']['output'];
+    /** Crowdy Studio project this version was deployed from, when known. */
+    projectId: Maybe<Scalars['String']['output']>;
     /** JSON source map. Null for non-authors of closed-source code; P1 exposes no moderation override. */
     sourceFilesJson: Maybe<Scalars['String']['output']>;
+    /** Project revision the source was read at (STUDIO projects). */
+    sourceRevision: Maybe<Scalars['BigInt']['output']>;
     /** Compile target. */
     target: PlayerComputeTarget;
     /** Version UUID. */
@@ -7606,14 +7685,16 @@ export type Query = {
     crowdyStudioAgentUsage: CrowdyStudioAgentUsagePage;
     /** List the current immutable versions of published Crowdy Studio-curated common files for one app. Requires an app-scoped token for appId; unlike private player source, this catalog content is intentionally readable by players in that app. Results are bounded and may be filtered by target. */
     crowdyStudioCommonFiles: Array<CrowdyStudioCommonFile>;
-    /** One UTF-8 file from the bound repository, with its blob SHA. */
+    /** One UTF-8 file from the bound repository at one commit (default: githubSha), with its blob SHA. */
     crowdyStudioGitHubFile: CrowdyStudioGitHubFile;
+    /** Where the SERVER and CLIENT crates live in the bound repository, resolved from crowdy.json (or inferred from the tree) at one commit. The only layout grammar: clients must not parse crowdy.json themselves. */
+    crowdyStudioGitHubLayout: CrowdyStudioGitHubLayout;
     /** Repositories the caller granted to their Crowdy Studio installation. Identity session only. */
     crowdyStudioGitHubRepos: Array<CrowdyStudioGitHubRepo>;
-    /** GitHub connection for the caller and the repository bound to a Crowdy Studio project. GitHub is a Studio filesystem capability, not a login provider. */
+    /** GitHub connection for the caller and the repository bound to a Crowdy Studio project, with the commit the project mirror is at (githubSha). GitHub is a Studio filesystem capability, not a login provider, and it is never required: a project starts in Crowdy Studio and may be bound later. */
     crowdyStudioGitHubStatus: CrowdyStudioGitHubStatus;
-    /** Recursive file list of the repository bound to the project (Git Trees API). */
-    crowdyStudioGitHubTree: Array<CrowdyStudioGitHubTreeEntry>;
+    /** Recursive file list of the repository bound to the project at one commit (default: githubSha, the mirror commit). */
+    crowdyStudioGitHubTree: CrowdyStudioGitHubTree;
     /** List the authenticated player’s private reusable Crowdy Studio source files in one app. Requires an app-scoped token for appId; cross-user entries are never visible, including to grid owners or Crowdy Studio operators. The bounded result defaults to 50. */
     crowdyStudioLibraryFiles: Array<CrowdyStudioLibraryFile>;
     /** The caller's own model usage in this app: today's request count and rate-carded charge against the policy ceiling, the payer (PLAYER wallet by default, ORG when the app elected it, PLATFORM while platform-funded), and the most recent requests. Counts and charges only; no prompts or provider bodies exist to return. Requires 'use_studio_agent'. */
@@ -8143,12 +8224,15 @@ export type QueryCrowdyStudioCommonFilesArgs = {
 export type QueryCrowdyStudioGitHubFileArgs = {
     input: CrowdyStudioGitHubFileInput;
 };
+export type QueryCrowdyStudioGitHubLayoutArgs = {
+    input: CrowdyStudioGitHubAtCommitInput;
+};
 export type QueryCrowdyStudioGitHubStatusArgs = {
     appId?: InputMaybe<Scalars['BigInt']['input']>;
     projectId?: InputMaybe<Scalars['String']['input']>;
 };
 export type QueryCrowdyStudioGitHubTreeArgs = {
-    input: CrowdyStudioGitHubProjectInput;
+    input: CrowdyStudioGitHubAtCommitInput;
 };
 export type QueryCrowdyStudioLibraryFilesArgs = {
     appId: Scalars['BigInt']['input'];
@@ -9345,11 +9429,6 @@ export type SetCrowdyStudioAgentPlatformPolicyInput = {
     /** Optional per-turn limit patch. */
     turnLimits?: InputMaybe<CrowdyStudioAgentTurnLimitsInput>;
 };
-export type SetCrowdyStudioGitHubAutosaveInput = {
-    appId: Scalars['BigInt']['input'];
-    autosave: Scalars['Boolean']['input'];
-    projectId: Scalars['String']['input'];
-};
 /** Optimistically archive or restore one caller-owned personal-library file. */
 export type SetCrowdyStudioLibraryFileArchivedInput = {
     /** App tenant that owns the private library entry. */
@@ -13038,6 +13117,11 @@ export type CrowdyStudioProjectFieldsFragment = {
     archivedAt: string | null;
     fileCount: number;
     totalBytes: string;
+    source: CrowdyStudioProjectSource;
+    githubOwner: string | null;
+    githubRepo: string | null;
+    githubBranch: string | null;
+    githubSha: string | null;
     createdAt: string;
     updatedAt: string;
     files: Array<{
@@ -13072,6 +13156,11 @@ export type CrowdyStudioProjectsQuery = {
         pairingPreference: CrowdyStudioPairingPreference;
         revision: string;
         archived: boolean;
+        source: CrowdyStudioProjectSource;
+        githubOwner: string | null;
+        githubRepo: string | null;
+        githubBranch: string | null;
+        githubSha: string | null;
         updatedAt: string;
     }>;
 };
@@ -13099,6 +13188,11 @@ export type CrowdyStudioProjectQuery = {
         archivedAt: string | null;
         fileCount: number;
         totalBytes: string;
+        source: CrowdyStudioProjectSource;
+        githubOwner: string | null;
+        githubRepo: string | null;
+        githubBranch: string | null;
+        githubSha: string | null;
         createdAt: string;
         updatedAt: string;
         files: Array<{
@@ -13139,6 +13233,11 @@ export type CrowdyStudioProjectCreateMutation = {
         archivedAt: string | null;
         fileCount: number;
         totalBytes: string;
+        source: CrowdyStudioProjectSource;
+        githubOwner: string | null;
+        githubRepo: string | null;
+        githubBranch: string | null;
+        githubSha: string | null;
         createdAt: string;
         updatedAt: string;
         files: Array<{
@@ -13179,6 +13278,11 @@ export type CrowdyStudioProjectSaveMutation = {
         archivedAt: string | null;
         fileCount: number;
         totalBytes: string;
+        source: CrowdyStudioProjectSource;
+        githubOwner: string | null;
+        githubRepo: string | null;
+        githubBranch: string | null;
+        githubSha: string | null;
         createdAt: string;
         updatedAt: string;
         files: Array<{
@@ -13295,6 +13399,11 @@ export type CrowdyStudioProjectImportFileMutation = {
         archivedAt: string | null;
         fileCount: number;
         totalBytes: string;
+        source: CrowdyStudioProjectSource;
+        githubOwner: string | null;
+        githubRepo: string | null;
+        githubBranch: string | null;
+        githubSha: string | null;
         createdAt: string;
         updatedAt: string;
         files: Array<{
@@ -16378,6 +16487,9 @@ export type PlayerWasmModuleVersionFieldsFragment = {
     compileStatus: string;
     compileLog: string | null;
     compiledSizeBytes: string | null;
+    projectId: string | null;
+    sourceRevision: string | null;
+    githubCommitSha: string | null;
     createdAt: string;
 };
 export type PlayerComputeDeployMutationVariables = Exact<{
@@ -16396,6 +16508,9 @@ export type PlayerComputeDeployMutation = {
         compileStatus: string;
         compileLog: string | null;
         compiledSizeBytes: string | null;
+        projectId: string | null;
+        sourceRevision: string | null;
+        githubCommitSha: string | null;
         createdAt: string;
     };
 };
@@ -16478,6 +16593,9 @@ export type PlayerComputeVersionsQuery = {
         compileStatus: string;
         compileLog: string | null;
         compiledSizeBytes: string | null;
+        projectId: string | null;
+        sourceRevision: string | null;
+        githubCommitSha: string | null;
         createdAt: string;
     }>;
 };