Puddle

@mesgme/puddlev2026.09.03.4· 8d agoMODELS

01README

Puddle — internal small-app request and assessment platform

02Models3

@mesgme/puddle/requestv2026.09.02.2extensions/models/request.ts

Global Arguments

Argument	Type	Required
title	string	yes
requester	string	yes
acceptanceUser	string	yes
publicCollective?	string	no
privateCollective?	string	no
notifyUrl?	string	no
notifyToken?	string	no
sourceRef?	string	no

fn draft(problemDescription?: string, currentProcess?: string, effortPerOccurrence?: string, constraints?: array, prefersLocal?: boolean)

Save the initial draft. Call once to persist the request before submitting.

Argument	Type	Required
problemDescription?	string	no
currentProcess?	string	no
effortPerOccurrence?	string	no
constraints?	array	no
prefersLocal?	boolean	no

fn submit(problemDescription: string, currentProcess: string, effortPerOccurrence?: string, constraints?: array, prefersLocal?: boolean)

Submit the request. Requires draft or needs_clarification state. Advances to submitted.

Argument	Type	Required
problemDescription	string	yes
currentProcess	string	yes
effortPerOccurrence?	string	no
constraints?	array	no
prefersLocal?	boolean	no

fn requestClarification(question: string)

Flag the request for clarification. Requires submitted state. Advances to needs_clarification.

Argument	Type	Required	Description
question	string	yes

fn match(matchedApp: string)

Record that an existing app matches this request. Requires submitted state. Advances to matched.

Argument	Type	Required	Description
matchedApp	string	yes

fn triage(notes?: string)

Mark the request as triaged. Requires submitted or matched state. Advances to triaged.

Argument	Type	Required	Description
notes?	string	no

fn makeAvailable(notes?: string)

Make the request available for builders. Requires triaged or claimed state. Advances to available.

Argument	Type	Required	Description
notes?	string	no

fn claim(builder: string, timeBox?: string)

Claim the request for investigation. Requires available state. Advances to claimed.

Argument	Type	Required	Description
builder	string	yes
timeBox?	string	no

fn specify(notes?: string)

Begin specification. Requires claimed or triaged state. Advances to in_specification.

Argument	Type	Required	Description
notes?	string	no

fn assessDelivery(rationale: string, requesterAccess: object, entryPointRef?: string, valueMeasurement: enum, alternativesConsidered?: array, assessedBy: string)

Record the chosen delivery method. Requires in_specification state. Advances to delivery_assessment.

Argument	Type	Required
rationale	string	yes
requesterAccess	object	yes
entryPointRef?	string	no
valueMeasurement	enum	yes
alternativesConsidered?	array	no
assessedBy	string	yes

fn reviewSpecification(verdict: enum, findings: array, reviewer: string, rationale?: string)

Adversarial review of the specification and delivery method against Puddle product rules.

Argument	Type	Required
verdict	enum	yes
findings	array	yes
reviewer	string	yes
rationale?	string	no

fn develop(implementationRef?: string, changesRequested?: string)

Begin development. Requires specification_review or in_acceptance state. Advances to in_development.

Argument	Type	Required	Description
implementationRef?	string	no
changesRequested?	string	no

fn startAcceptance(notes?: string)

Begin acceptance testing. Requires in_development state. Advances to in_acceptance.

Argument	Type	Required	Description
notes?	string	no

fn deliver(realisedEffort?: string, producedExpectedResult: boolean, omittedAnything?: string, inventedOrAltered?: string, easierThanPreviousMethod: boolean, manualCorrectionRequired?: string, wouldUseAgain: boolean, shouldBeShared?: boolean, acceptedBy: string)

Mark the request as delivered. Requires in_acceptance state. Advances to delivered.

Argument	Type	Required
realisedEffort?	string	no
producedExpectedResult	boolean	yes
omittedAnything?	string	no
inventedOrAltered?	string	no
easierThanPreviousMethod	boolean	yes
manualCorrectionRequired?	string	no
wouldUseAgain	boolean	yes
shouldBeShared?	boolean	no
acceptedBy	string	yes

fn assess(rationale: string, manualEffort?: string, recurrence?: string, reuse?: string, buildEffort?: string, maintenanceBurden?: string, risk?: string, learningValue?: string, timeSensitivity?: string, searched: boolean, extensionsFound: array, conclusion: string)

Record a worth-building assessment. Not a state transition — can run at any lifecycle stage.

Argument	Type	Required
rationale	string	yes
manualEffort?	string	no
recurrence?	string	no
reuse?	string	no
buildEffort?	string	no
maintenanceBurden?	string	no
risk?	string	no
learningValue?	string	no
timeSensitivity?	string	no
searched	boolean	yes
extensionsFound	array	yes
conclusion	string	yes

fn approve(approvedBy: string, note?: string)

Owner sign-off to allow the next gated transition.

Argument	Type	Required	Description
approvedBy	string	yes
note?	string	no

fn decline(reason: string)

Decline the request. Requires a reason. Can be called from most non-terminal states.

Argument	Type	Required	Description
reason	string	yes

fn withdraw(reason?: string)

Withdraw the request. Can be called from most non-terminal states.

Argument	Type	Required	Description
reason?	string	no

fn reviewPublication(artifactPath: string, selfPackage?: string)

Scan the artifact for publication risks and advance to publication_review.

Argument	Type	Required	Description
artifactPath	string	yes
selfPackage?	string	no

fn decidePublication(destination: enum, confirmedBy: string, rationale: string)

Record the publication decision. Requires publication_review state. Advances to publication_decided.

Argument	Type	Required
destination	enum	yes
confirmedBy	string	yes
rationale	string	yes

Resources

request(infinite)— Current state of the App Request including all §7.2 fields, a transitions log, and delivery metadata.

assessment(infinite)— Worth-building assessment (puddle.md §10) including the §10.2 decision category, §10.1 dimensions, and §9 capability search findings.

deliveryAssessment(infinite)— Delivery method assessment record. Written by assessDelivery. Records the chosen delivery method, requester access requirements, and entry-point ref within the app repo.

specificationReview(infinite)— Adversarial specification review record. Written by reviewSpecification. Contains verdict, findings, reviewer, and rationale.

publication(infinite)— Publication risk scan and decision record. Written by reviewPublication (scan fields) and updated by decidePublication (decision fields).

@mesgme/puddle/intakev2026.08.17.1extensions/models/puddle_intake.ts

fn list_candidate_requests()

Fetch candidate app requests from the puddle-ui database.

Resources

candidate_requests(15m)— List of candidate app requests from the puddle-ui database, for Puddle intake.

@mesgme/puddle/workflow-syncv2026.09.03.4extensions/models/workflow_sync.ts

fn sync()

Fan-out sync: fetch workflow YAML from GitHub for each app and write to the serve workflows/ directory.

Resources

sync_report(1h)— Report of the most recent workflow sync run — per-app status, collisions, summary.

03Previous Versions3

2026.09.03.3Sep 3, 2026

2026.09.03.2Sep 3, 2026

Modified 1 models

2026.09.03.1Sep 3, 2026

04Stats

50 / 100

Downloads

Archive size

49.7 KB

Has README or module doc0/2missing
README has a code example0/1missing
README is substantive0/1pending
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared0/1missing
Verified public repository0/2missing

05Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64