What stable interactive Modeling Session workflow should enumerate eligible unmodeled or stale records, read canonical descriptions and variant context, generate and validate one mechanic locally, obtain per-record chat confirmation, submit through the existing owning ISAC action, and resume safely from canonical state after interruption?
Part of #1
Blocked by: #2, #3
## Question
What stable interactive Modeling Session workflow should enumerate eligible unmodeled or stale records, read canonical descriptions and variant context, generate and validate one mechanic locally, obtain per-record chat confirmation, submit through the existing owning ISAC action, and resume safely from canonical state after interruption?
SHD.build issues revocable user-owned agent tokens. The server stores only a token hash and records owner, name, scopes, expiry, revocation, creation, and last-use timestamps. Every request resolves to the owning Registered Agent for authorization and audit evidence.
The contract uses JSON under /api/isac/mechanic-modeling. Reading candidates requires a modeling-read scope plus data.view. Generation requires a modeling-generate scope plus ai.mechanic.generate. A successful draft reaches Canonical Game Data only through the owner's mutation service and the caller's existing data.manage or data.propose authority. A token cannot grant authority its owner lacks.
Candidate enumeration
GET /api/isac/mechanic-modeling/candidates returns publishable owners whose model lifecycle is absent or stale. Query parameters support owner-type and lifecycle filters. The four owner types are Talent, OS Protocol Talent, Skill Chip Talent, and Specialization tree-rank effect.
The server orders candidates by owner type and stable owner ID and uses an opaque cursor. Each item contains:
owner type, stable owner ID, name, and canonical route reference;
lifecycle and selected model revision metadata;
current source fingerprint and fingerprint contract version;
required variant identifiers and materialized authored descriptions;
mechanic contract and prompt contract versions;
whether the caller can publish, propose, or only generate.
The server never returns unpublished incomplete prose as eligible. The cursor does not create a snapshot. Clients retain their own candidate manifests and must send each item's expected source fingerprint when generating. A later source edit produces a stale-source result rather than a model for changed evidence.
Single-record command
POST /api/isac/mechanic-modeling/records/{ownerType}/{ownerId}/generate processes one owner. The request contains the expected source fingerprint, an optional bounded clarification transcript, and no client-authored source description or Mechanic Program seed. The server reloads the canonical materialized descriptions and variant contract.
The command requires an Idempotency-Key. SHD.build persists a receipt keyed by Agent and key, with a canonical request hash and structured response. An exact retry returns the receipt without another model call, mutation, proposal, or audit event. Reusing the key with different input returns 409 idempotency_conflict.
The server runs generation outside the database transaction and validates the response against the installed profile, Attribute catalog, draft grammar, and runtime. If it receives a valid draft, it starts a per-record transaction, reloads the owner, recomputes the source fingerprint, and rejects drift. It then calls the same owner mutation service used by ISAC and contribution approval.
A caller with data.manage creates and selects an immutable model revision. A caller with data.propose creates one owner-scoped Contribution Proposal. A caller with neither permission receives the validated generation result without a canonical mutation. No bulk transaction spans owners.
Result envelope
Every response includes receipt ID, idempotency key, owner identity, expected and observed source fingerprints, request ID, model and contract versions, token usage, timestamps, and one terminal command result:
model_persisted: model revision ID, readiness, audit event ID, and selected revision;
proposal_created: proposal ID, dependencies, and generated revision payload fingerprint;
clarification_required: bounded questions and the transcript entries the client must echo with answers under a new idempotency key;
capability_gap: typed gaps and any verified capability-branch reference;
stale_source: observed fingerprint and a retryable instruction to re-enumerate;
validation_failed: stable error codes and field paths;
generation_failed: retryability, retry-after data when applicable, and no canonical mutation.
Clients resend the complete bounded clarification transcript on each attempt. SHD.build does not persist a conversation or server-side continuation. Each attempt receives its own durable receipt and rechecks the source fingerprint.
Client-managed bulk execution
SHD.build does not add a bulk job table, run dashboard, server checkpoint, or coverage metrics. A client may enumerate candidates, save the returned list, choose concurrency and budgets, and call the single-record command for each item. It records its own cursor and aggregate summary.
Successful records remain committed when another record fails. The client resumes only pending or retryable items and uses the original idempotency key for an uncertain request outcome. It uses a new key after changing the transcript or expected source fingerprint.
Rate limits apply per token owner and globally through shared durable state rather than process-local counters. A retryable limit response includes Retry-After and consumes no generation or mutation receipt beyond the recorded failure result.
Acceptance checks
Revocation and expiry stop token access without ending browser sessions.
Token scopes never elevate the owning Agent's permissions.
Enumeration covers every publishable absent or stale owner and excludes incomplete proposals.
Stable cursors and expected fingerprints prevent changed prose from receiving an old model.
Exact idempotent retries duplicate neither AI usage nor canonical side effects.
Clarification, capability-gap, stale-source, proposal, persisted, validation, and retryable failures have contract tests.
Direct writes and proposals use the owning service, validation, transaction, and audit path.
One record's failure cannot roll back another record.
No response or audit event stores token secrets or unnecessary source prose.
# Agent modeling contract
## Access and permissions
SHD.build issues revocable user-owned agent tokens. The server stores only a token hash and records owner, name, scopes, expiry, revocation, creation, and last-use timestamps. Every request resolves to the owning Registered Agent for authorization and audit evidence.
The contract uses JSON under `/api/isac/mechanic-modeling`. Reading candidates requires a modeling-read scope plus `data.view`. Generation requires a modeling-generate scope plus `ai.mechanic.generate`. A successful draft reaches Canonical Game Data only through the owner's mutation service and the caller's existing `data.manage` or `data.propose` authority. A token cannot grant authority its owner lacks.
## Candidate enumeration
`GET /api/isac/mechanic-modeling/candidates` returns publishable owners whose model lifecycle is `absent` or `stale`. Query parameters support owner-type and lifecycle filters. The four owner types are Talent, OS Protocol Talent, Skill Chip Talent, and Specialization tree-rank effect.
The server orders candidates by owner type and stable owner ID and uses an opaque cursor. Each item contains:
- owner type, stable owner ID, name, and canonical route reference;
- lifecycle and selected model revision metadata;
- current source fingerprint and fingerprint contract version;
- required variant identifiers and materialized authored descriptions;
- mechanic contract and prompt contract versions;
- whether the caller can publish, propose, or only generate.
The server never returns unpublished incomplete prose as eligible. The cursor does not create a snapshot. Clients retain their own candidate manifests and must send each item's expected source fingerprint when generating. A later source edit produces a stale-source result rather than a model for changed evidence.
## Single-record command
`POST /api/isac/mechanic-modeling/records/{ownerType}/{ownerId}/generate` processes one owner. The request contains the expected source fingerprint, an optional bounded clarification transcript, and no client-authored source description or Mechanic Program seed. The server reloads the canonical materialized descriptions and variant contract.
The command requires an `Idempotency-Key`. SHD.build persists a receipt keyed by Agent and key, with a canonical request hash and structured response. An exact retry returns the receipt without another model call, mutation, proposal, or audit event. Reusing the key with different input returns `409 idempotency_conflict`.
The server runs generation outside the database transaction and validates the response against the installed profile, Attribute catalog, draft grammar, and runtime. If it receives a valid draft, it starts a per-record transaction, reloads the owner, recomputes the source fingerprint, and rejects drift. It then calls the same owner mutation service used by ISAC and contribution approval.
A caller with `data.manage` creates and selects an immutable model revision. A caller with `data.propose` creates one owner-scoped Contribution Proposal. A caller with neither permission receives the validated generation result without a canonical mutation. No bulk transaction spans owners.
## Result envelope
Every response includes receipt ID, idempotency key, owner identity, expected and observed source fingerprints, request ID, model and contract versions, token usage, timestamps, and one terminal command result:
- `model_persisted`: model revision ID, readiness, audit event ID, and selected revision;
- `proposal_created`: proposal ID, dependencies, and generated revision payload fingerprint;
- `clarification_required`: bounded questions and the transcript entries the client must echo with answers under a new idempotency key;
- `capability_gap`: typed gaps and any verified capability-branch reference;
- `stale_source`: observed fingerprint and a retryable instruction to re-enumerate;
- `validation_failed`: stable error codes and field paths;
- `generation_failed`: retryability, retry-after data when applicable, and no canonical mutation.
Clients resend the complete bounded clarification transcript on each attempt. SHD.build does not persist a conversation or server-side continuation. Each attempt receives its own durable receipt and rechecks the source fingerprint.
## Client-managed bulk execution
SHD.build does not add a bulk job table, run dashboard, server checkpoint, or coverage metrics. A client may enumerate candidates, save the returned list, choose concurrency and budgets, and call the single-record command for each item. It records its own cursor and aggregate summary.
Successful records remain committed when another record fails. The client resumes only pending or retryable items and uses the original idempotency key for an uncertain request outcome. It uses a new key after changing the transcript or expected source fingerprint.
Rate limits apply per token owner and globally through shared durable state rather than process-local counters. A retryable limit response includes `Retry-After` and consumes no generation or mutation receipt beyond the recorded failure result.
## Acceptance checks
- Revocation and expiry stop token access without ending browser sessions.
- Token scopes never elevate the owning Agent's permissions.
- Enumeration covers every publishable absent or stale owner and excludes incomplete proposals.
- Stable cursors and expected fingerprints prevent changed prose from receiving an old model.
- Exact idempotent retries duplicate neither AI usage nor canonical side effects.
- Clarification, capability-gap, stale-source, proposal, persisted, validation, and retryable failures have contract tests.
- Direct writes and proposals use the owning service, validation, transaction, and audit path.
- One record's failure cannot roll back another record.
- No response or audit event stores token secrets or unnecessary source prose.
The decision specification above now reflects the confirmed simplified workflow: an interactive Modeling Session, local generation, one-record chat confirmation, existing ISAC actions, and no application-side client or bulk-run infrastructure. Closing as resolved.
The decision specification above now reflects the confirmed simplified workflow: an interactive Modeling Session, local generation, one-record chat confirmation, existing ISAC actions, and no application-side client or bulk-run infrastructure. Closing as resolved.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Part of #1
Blocked by: #2, #3
Question
What stable interactive Modeling Session workflow should enumerate eligible unmodeled or stale records, read canonical descriptions and variant context, generate and validate one mechanic locally, obtain per-record chat confirmation, submit through the existing owning ISAC action, and resume safely from canonical state after interruption?
Agent modeling contract
Access and permissions
SHD.build issues revocable user-owned agent tokens. The server stores only a token hash and records owner, name, scopes, expiry, revocation, creation, and last-use timestamps. Every request resolves to the owning Registered Agent for authorization and audit evidence.
The contract uses JSON under
/api/isac/mechanic-modeling. Reading candidates requires a modeling-read scope plusdata.view. Generation requires a modeling-generate scope plusai.mechanic.generate. A successful draft reaches Canonical Game Data only through the owner's mutation service and the caller's existingdata.manageordata.proposeauthority. A token cannot grant authority its owner lacks.Candidate enumeration
GET /api/isac/mechanic-modeling/candidatesreturns publishable owners whose model lifecycle isabsentorstale. Query parameters support owner-type and lifecycle filters. The four owner types are Talent, OS Protocol Talent, Skill Chip Talent, and Specialization tree-rank effect.The server orders candidates by owner type and stable owner ID and uses an opaque cursor. Each item contains:
The server never returns unpublished incomplete prose as eligible. The cursor does not create a snapshot. Clients retain their own candidate manifests and must send each item's expected source fingerprint when generating. A later source edit produces a stale-source result rather than a model for changed evidence.
Single-record command
POST /api/isac/mechanic-modeling/records/{ownerType}/{ownerId}/generateprocesses one owner. The request contains the expected source fingerprint, an optional bounded clarification transcript, and no client-authored source description or Mechanic Program seed. The server reloads the canonical materialized descriptions and variant contract.The command requires an
Idempotency-Key. SHD.build persists a receipt keyed by Agent and key, with a canonical request hash and structured response. An exact retry returns the receipt without another model call, mutation, proposal, or audit event. Reusing the key with different input returns409 idempotency_conflict.The server runs generation outside the database transaction and validates the response against the installed profile, Attribute catalog, draft grammar, and runtime. If it receives a valid draft, it starts a per-record transaction, reloads the owner, recomputes the source fingerprint, and rejects drift. It then calls the same owner mutation service used by ISAC and contribution approval.
A caller with
data.managecreates and selects an immutable model revision. A caller withdata.proposecreates one owner-scoped Contribution Proposal. A caller with neither permission receives the validated generation result without a canonical mutation. No bulk transaction spans owners.Result envelope
Every response includes receipt ID, idempotency key, owner identity, expected and observed source fingerprints, request ID, model and contract versions, token usage, timestamps, and one terminal command result:
model_persisted: model revision ID, readiness, audit event ID, and selected revision;proposal_created: proposal ID, dependencies, and generated revision payload fingerprint;clarification_required: bounded questions and the transcript entries the client must echo with answers under a new idempotency key;capability_gap: typed gaps and any verified capability-branch reference;stale_source: observed fingerprint and a retryable instruction to re-enumerate;validation_failed: stable error codes and field paths;generation_failed: retryability, retry-after data when applicable, and no canonical mutation.Clients resend the complete bounded clarification transcript on each attempt. SHD.build does not persist a conversation or server-side continuation. Each attempt receives its own durable receipt and rechecks the source fingerprint.
Client-managed bulk execution
SHD.build does not add a bulk job table, run dashboard, server checkpoint, or coverage metrics. A client may enumerate candidates, save the returned list, choose concurrency and budgets, and call the single-record command for each item. It records its own cursor and aggregate summary.
Successful records remain committed when another record fails. The client resumes only pending or retryable items and uses the original idempotency key for an uncertain request outcome. It uses a new key after changing the transcript or expected source fingerprint.
Rate limits apply per token owner and globally through shared durable state rather than process-local counters. A retryable limit response includes
Retry-Afterand consumes no generation or mutation receipt beyond the recorded failure result.Acceptance checks
Decision specification recorded above. The contract defines scoped agent access, candidate enumeration, single-record idempotent generation, clarification retries, owner-service persistence, per-record results, and client-managed bulk execution. Closing as resolved.
Define the agent modeling contractto Define the Modeling Client contractDefine the Modeling Client contractto Define the Modeling Session contractThe decision specification above now reflects the confirmed simplified workflow: an interactive Modeling Session, local generation, one-record chat confirmation, existing ISAC actions, and no application-side client or bulk-run infrastructure. Closing as resolved.