PTSIP 0.3.2__tar.gz → 0.3.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ptsip-0.3.4/PKG-INFO +327 -0
- ptsip-0.3.4/README.md +295 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/pyproject.toml +8 -5
- ptsip-0.3.4/src/PTSIP.egg-info/PKG-INFO +327 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/PTSIP.egg-info/SOURCES.txt +4 -0
- ptsip-0.3.4/src/ptsip/adoption.py +225 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/app/client.py +3 -3
- ptsip-0.3.4/src/ptsip/app/github_authority.py +629 -0
- ptsip-0.3.4/src/ptsip/app/github_reconciliation.py +328 -0
- ptsip-0.3.4/src/ptsip/app/local_client.py +111 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/generator.py +10 -5
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/generator_core.py +2 -2
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/resolution/profile_projection.py +12 -33
- ptsip-0.3.4/src/ptsip/cli.py +754 -0
- ptsip-0.3.4/src/ptsip/constants.py +9 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/specdata/ptsip-agent-classification.schema.json +28 -6
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/specdata/ptsip-artifact-evidence.schema.json +1 -1
- ptsip-0.3.4/src/ptsip/specdata/ptsip-diagnostic.schema.json +58 -0
- ptsip-0.3.4/src/ptsip/specdata/ptsip-profile.schema.json +188 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/specdata/ptsip-registry.yaml +103 -3
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/storage/local_state.py +8 -0
- ptsip-0.3.2/PKG-INFO +0 -338
- ptsip-0.3.2/README.md +0 -307
- ptsip-0.3.2/src/PTSIP.egg-info/PKG-INFO +0 -338
- ptsip-0.3.2/src/ptsip/cli.py +0 -434
- ptsip-0.3.2/src/ptsip/constants.py +0 -9
- ptsip-0.3.2/src/ptsip/specdata/ptsip-diagnostic.schema.json +0 -29
- ptsip-0.3.2/src/ptsip/specdata/ptsip-profile.schema.json +0 -310
- {ptsip-0.3.2 → ptsip-0.3.4}/LICENSE +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/MANIFEST.in +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/setup.cfg +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/PTSIP.egg-info/dependency_links.txt +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/PTSIP.egg-info/entry_points.txt +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/PTSIP.egg-info/requires.txt +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/PTSIP.egg-info/top_level.txt +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/__main__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/app/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/app/github_client.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/app/server.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/app/service.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/app/store.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/artifact_evidence.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/build_resolution.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/i18n.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/model.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/render.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/resolution/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/resolution/model.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/resolution/parser.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/resolution/resolver.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/transports/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/clarification/transports/github_issue.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/conformance.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/conformance_audit.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/conformance_engine.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/doctor.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/components.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/dependencies.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/dependencies_030.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/dotnet.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/go.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/inventory.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/javascript.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/lexing.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/inspection/source_adapters.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/lifecycle_evidence.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/model.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/pilot/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/pilot/runner.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/repository/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/repository/discover.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/repository/remote.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/repository/snapshot.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/review_evidence.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/spec_identity.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/storage/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/topology.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/validation/__init__.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/validation/components.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/validation/profile.py +0 -0
- {ptsip-0.3.2 → ptsip-0.3.4}/src/ptsip/validation/rules.py +0 -0
ptsip-0.3.4/PKG-INFO
ADDED
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: PTSIP
|
|
3
|
+
Version: 0.3.4
|
|
4
|
+
Summary: Reference development tooling for the Product-Toolchain SDK Isolation Policy
|
|
5
|
+
Author: Kinirin
|
|
6
|
+
Maintainer: Kinirin
|
|
7
|
+
License-Expression: Apache-2.0
|
|
8
|
+
Project-URL: Homepage, https://github.com/Kinirin/PTSIP
|
|
9
|
+
Project-URL: Specification, https://github.com/Kinirin/PTSIP
|
|
10
|
+
Project-URL: Issues, https://github.com/Kinirin/PTSIP/issues
|
|
11
|
+
Keywords: architecture,sdk,toolchain,governance,validation,ptsip
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Environment :: Console
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
21
|
+
Requires-Python: >=3.11
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: PyYAML<7,>=6.0
|
|
25
|
+
Requires-Dist: jsonschema<5,>=4.23
|
|
26
|
+
Provides-Extra: github-app
|
|
27
|
+
Requires-Dist: PyJWT[crypto]<3,>=2.10; extra == "github-app"
|
|
28
|
+
Provides-Extra: dev
|
|
29
|
+
Requires-Dist: build<2,>=1.2; extra == "dev"
|
|
30
|
+
Requires-Dist: pytest<9,>=8; extra == "dev"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
<p align="right">
|
|
34
|
+
English | <a href="README.ko.md">한국어</a>
|
|
35
|
+
</p>
|
|
36
|
+
|
|
37
|
+
# PTSIP — Product–Toolchain SDK Isolation Policy
|
|
38
|
+
|
|
39
|
+
**Status:** Draft project-defined specification
|
|
40
|
+
**Specification family:** `0.3.4-draft`
|
|
41
|
+
**Active normative snapshot:** `b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e`<br>
|
|
42
|
+
**License:** Apache License 2.0
|
|
43
|
+
|
|
44
|
+
PTSIP is an architecture policy for keeping Product SDK responsibility separate from development Toolchain SDK responsibility while preserving explicit contracts, reproducible conformance, and multi-environment architecture-decision consistency.
|
|
45
|
+
|
|
46
|
+
> **Purpose precedes reuse.** Classify a component by why it exists and which lifecycle owns it before considering code sharing.
|
|
47
|
+
|
|
48
|
+
## Architecture model
|
|
49
|
+
|
|
50
|
+
PTSIP has exactly three architectural classifications:
|
|
51
|
+
|
|
52
|
+
| Classification | Meaning |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| `PRODUCT` | Product-owned runtime/library/SDK/component responsibility. |
|
|
55
|
+
| `TOOLCHAIN` | Development-tooling-owned SDK/component responsibility. |
|
|
56
|
+
| `NEUTRAL_CONTRACT` | Deliberately non-executable, independently governed contract responsibility. |
|
|
57
|
+
|
|
58
|
+
`UNKNOWN`, `CONFLICT`, `INCOMPLETE`, `PENDING`, and similar states are workflow/evaluation states, not additional architecture planes.
|
|
59
|
+
|
|
60
|
+
The core boundary is:
|
|
61
|
+
|
|
62
|
+
```text
|
|
63
|
+
Toolchain SDK ---> Product source / artifacts
|
|
64
|
+
inspect / validate / generate / migrate / package
|
|
65
|
+
|
|
66
|
+
Product SDK -X-> Toolchain implementation
|
|
67
|
+
runtime / shipped dependency prohibited
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Shared semantics should prefer a Neutral Contract over one project-local executable package owned by both planes.
|
|
71
|
+
|
|
72
|
+
## Install and use
|
|
73
|
+
|
|
74
|
+
PTSIP requires Python 3.11 or newer.
|
|
75
|
+
|
|
76
|
+
```powershell
|
|
77
|
+
pip install PTSIP
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Common commands:
|
|
81
|
+
|
|
82
|
+
```powershell
|
|
83
|
+
ptsip --version
|
|
84
|
+
ptsip spec
|
|
85
|
+
ptsip doctor .
|
|
86
|
+
ptsip inspect .
|
|
87
|
+
ptsip pilot .
|
|
88
|
+
ptsip adopt --help
|
|
89
|
+
ptsip validate .
|
|
90
|
+
ptsip clarify .
|
|
91
|
+
ptsip gate .
|
|
92
|
+
ptsip resolve --help
|
|
93
|
+
ptsip conform .
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
For source development:
|
|
97
|
+
|
|
98
|
+
```powershell
|
|
99
|
+
pip install -e ".[dev]"
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Specification and Tool lifecycle
|
|
103
|
+
|
|
104
|
+
The **PTSIP Specification** and **PTSIP Reference Tool** are independently versioned.
|
|
105
|
+
|
|
106
|
+
- `pyproject.toml` owns Tool/package source version;
|
|
107
|
+
- `ptsip --version` reports installed Tool version;
|
|
108
|
+
- `ptsip spec` reports the exact Specification family + immutable revision bound to that Tool;
|
|
109
|
+
- `spec/`, `schemas/`, and `registry/` contain canonical Specification assets;
|
|
110
|
+
- `src/ptsip/specdata/` contains matching embedded resources used by the Tool;
|
|
111
|
+
- GitHub Releases publish Tool and Specification release/design records.
|
|
112
|
+
|
|
113
|
+
The existing `spec-v0.3.4-draft` GitHub Release records the earlier design proposal. It remains an immutable historical checkpoint and is not moved. The active repository-identity-migration snapshot is `0.3.4-draft @ b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e`.
|
|
114
|
+
|
|
115
|
+
A Tool version number matching a Specification family number does not imply identity by itself.
|
|
116
|
+
|
|
117
|
+
## Consumer Repository non-intrusion
|
|
118
|
+
|
|
119
|
+
PTSIP does not require adopting repositories to create PTSIP-specific `docs/`, `tools/`, `.ptsip/`, cache, report, or hidden directories.
|
|
120
|
+
|
|
121
|
+
External inspection/Pilot tooling is read-only by default. Tool-owned operational state belongs outside the Consumer Repository unless the user explicitly chooses a repository path.
|
|
122
|
+
|
|
123
|
+
The default project-owned architecture declaration is repository-root `ptsip.yaml`; projects may consistently select another path with `--profile`.
|
|
124
|
+
|
|
125
|
+
Local state such as `control-plane.sqlite3` is not portable architecture authority and must not be Git-shared as repository-global coordination state.
|
|
126
|
+
|
|
127
|
+
## Explicit project adoption
|
|
128
|
+
|
|
129
|
+
Candidate discovery is evidence, not architecture authority. The project owner supplies architecture intent.
|
|
130
|
+
|
|
131
|
+
`0.3.4-draft` defines this structured adoption fact set:
|
|
132
|
+
|
|
133
|
+
```text
|
|
134
|
+
classification
|
|
135
|
+
purpose
|
|
136
|
+
shipped
|
|
137
|
+
runtime_required
|
|
138
|
+
lifecycle_owner
|
|
139
|
+
executable
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Canonical lifecycle owners are:
|
|
143
|
+
|
|
144
|
+
```text
|
|
145
|
+
PRODUCT
|
|
146
|
+
DEVELOPMENT_TOOLING
|
|
147
|
+
INDEPENDENT
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Example dry-run:
|
|
151
|
+
|
|
152
|
+
```powershell
|
|
153
|
+
ptsip adopt . `
|
|
154
|
+
--component tools `
|
|
155
|
+
--classification TOOLCHAIN `
|
|
156
|
+
--purpose "Repository-local generation tooling" `
|
|
157
|
+
--shipped no `
|
|
158
|
+
--runtime-required no `
|
|
159
|
+
--lifecycle-owner DEVELOPMENT_TOOLING `
|
|
160
|
+
--executable yes `
|
|
161
|
+
--json
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Apply only after reviewing the plan:
|
|
165
|
+
|
|
166
|
+
```powershell
|
|
167
|
+
ptsip adopt . `
|
|
168
|
+
--component tools `
|
|
169
|
+
--classification TOOLCHAIN `
|
|
170
|
+
--purpose "Repository-local generation tooling" `
|
|
171
|
+
--shipped no `
|
|
172
|
+
--runtime-required no `
|
|
173
|
+
--lifecycle-owner DEVELOPMENT_TOOLING `
|
|
174
|
+
--executable yes `
|
|
175
|
+
--apply `
|
|
176
|
+
--json
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Structured adoption preserves those facts losslessly in component declarations. `runtime_required` is not discarded, and canonical `lifecycle_owner` is not aliased to `release_owner`.
|
|
180
|
+
|
|
181
|
+
Boundary-root shorthand remains available for simple declarations, but a write-enabled structured adoption/resolution must refuse mutation when shorthand cannot preserve the full fact set.
|
|
182
|
+
|
|
183
|
+
## Decision Authority
|
|
184
|
+
|
|
185
|
+
PTSIP distinguishes:
|
|
186
|
+
|
|
187
|
+
```text
|
|
188
|
+
Specification
|
|
189
|
+
-> normative architecture / conformance / coordination rules
|
|
190
|
+
|
|
191
|
+
Decision Authority
|
|
192
|
+
-> which explicit architecture answer won
|
|
193
|
+
|
|
194
|
+
Project Profile
|
|
195
|
+
-> durable project-owned architecture declaration
|
|
196
|
+
|
|
197
|
+
Observed evidence
|
|
198
|
+
-> what repository/artifacts actually do
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
A Decision Authority is not a conformance oracle and does not replace `ptsip.yaml`.
|
|
202
|
+
|
|
203
|
+
## GitHub-coordinated Reference Tool profile
|
|
204
|
+
|
|
205
|
+
Reference Tool `0.3.4` demonstrates distributed coordination through a dedicated Git ref:
|
|
206
|
+
|
|
207
|
+
```text
|
|
208
|
+
refs/heads/ptsip-policy
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
GitHub storage details are implementation-specific. The Specification requires the semantics, not GitHub itself:
|
|
212
|
+
|
|
213
|
+
- stable coordination-domain + component-scope decision identity;
|
|
214
|
+
- first-valid-resolution-wins;
|
|
215
|
+
- ordered conditional mutation / stale-writer protection;
|
|
216
|
+
- authority freshness at architecture-sensitive boundaries;
|
|
217
|
+
- non-mutating absence lookup;
|
|
218
|
+
- deterministic reconciliation;
|
|
219
|
+
- fail-closed distributed behavior; and
|
|
220
|
+
- separation of global decision state from clone-local application state.
|
|
221
|
+
|
|
222
|
+
## Coding-agent decision gate
|
|
223
|
+
|
|
224
|
+
```powershell
|
|
225
|
+
ptsip gate . --component tools --json
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
In distributed mode, a complete local profile does **not** automatically bypass the authority check. The relevant local declaration is compared with current authority state.
|
|
229
|
+
|
|
230
|
+
| Local Project Profile | Distributed Authority | Required result |
|
|
231
|
+
| --- | --- | --- |
|
|
232
|
+
| declaration absent | no decision | pending only when the active operation actually needs a decision |
|
|
233
|
+
| declaration absent | resolved winner | validate and safely project winner locally |
|
|
234
|
+
| declaration present | no authority decision | use project declaration; do not fabricate authority history |
|
|
235
|
+
| declaration present + equivalent | resolved equivalent winner | resolved/consistent; no formatting rewrite required |
|
|
236
|
+
| declaration present + conflicting | resolved different winner | explicit authority/profile conflict; no silent overwrite |
|
|
237
|
+
| repository/profile changed during reconciliation | any authority state | stale; refuse application and re-analyze |
|
|
238
|
+
|
|
239
|
+
Semantic equivalence means architecture meaning, not YAML key order or whitespace.
|
|
240
|
+
|
|
241
|
+
If distributed coordination is selected but required freshness/safe mutation cannot be established, PTSIP fails the affected operation instead of silently creating a separate Local winner.
|
|
242
|
+
|
|
243
|
+
## Global decision state versus local projection
|
|
244
|
+
|
|
245
|
+
```text
|
|
246
|
+
GLOBAL
|
|
247
|
+
PENDING / RESOLVED
|
|
248
|
+
|
|
249
|
+
LOCAL CLONE / WORKTREE
|
|
250
|
+
missing / consistent / locally applied / stale / failed
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
A global winner does not mean every clone is already synchronized. A clone-local application receipt cannot change the winner.
|
|
254
|
+
|
|
255
|
+
PTSIP uses **action-time synchronization** rather than continuous polling.
|
|
256
|
+
|
|
257
|
+
## Enforced conformance
|
|
258
|
+
|
|
259
|
+
`ptsip conform` evaluates declaration + observed evidence + Product Artifact/build/lifecycle evidence + snapshot/coverage against Consumer Repository PTSIP rules.
|
|
260
|
+
|
|
261
|
+
Completed outcomes are only:
|
|
262
|
+
|
|
263
|
+
| Exit code | Outcome |
|
|
264
|
+
| --- | --- |
|
|
265
|
+
| `0` | `CONFORMANT` |
|
|
266
|
+
| `5` | `NON_CONFORMANT` |
|
|
267
|
+
| `6` | `INCOMPLETE` |
|
|
268
|
+
|
|
269
|
+
A valid Project Profile does not prove conformance. A resolved Decision Authority winner does not prove conformance. A zero-finding scan does not prove conformance when blocking evidence gaps remain.
|
|
270
|
+
|
|
271
|
+
For Enforced Conformance against a mutable draft, bind the exact immutable Specification revision.
|
|
272
|
+
|
|
273
|
+
## Reference Tool focus
|
|
274
|
+
|
|
275
|
+
The Reference Tool provides:
|
|
276
|
+
|
|
277
|
+
- read-only repository inspection and Pilot evidence;
|
|
278
|
+
- multi-language dependency/artifact evidence;
|
|
279
|
+
- deterministic clarification for missing intent;
|
|
280
|
+
- explicit project-owner adoption;
|
|
281
|
+
- on-demand decision gating and explicit resolution;
|
|
282
|
+
- GitHub-coordinated first-winner authority for multi-environment agents;
|
|
283
|
+
- gate-time authority freshness and reconciliation;
|
|
284
|
+
- fail-closed distributed coordination;
|
|
285
|
+
- local-only DecisionStore mode when intentionally selected;
|
|
286
|
+
- project-profile validation;
|
|
287
|
+
- Product Artifact evidence ingestion;
|
|
288
|
+
- evidence-relative Enforced Conformance and stable diagnostics.
|
|
289
|
+
|
|
290
|
+
## Repository map
|
|
291
|
+
|
|
292
|
+
| Area | Location | Purpose |
|
|
293
|
+
| --- | --- | --- |
|
|
294
|
+
| Normative Specification | [`spec/`](spec/) | Architecture, terminology, and conformance rules. |
|
|
295
|
+
| Machine-readable registry | [`registry/`](registry/) | Canonical terms/rule IDs/metadata. |
|
|
296
|
+
| Schemas | [`schemas/`](schemas/) | Project Profile and interoperability schemas. |
|
|
297
|
+
| Agent contract | [`agents/AGENT-CONTRACT.md`](agents/AGENT-CONTRACT.md) | Coding-agent operational contract. |
|
|
298
|
+
| Adoption guide | [`adoption/ADOPTION-GUIDE.md`](adoption/ADOPTION-GUIDE.md) | Controlled adoption sequence. |
|
|
299
|
+
| Reference architecture | [`reference/REFERENCE-ARCHITECTURE.md`](reference/REFERENCE-ARCHITECTURE.md) | Informative architecture guidance. |
|
|
300
|
+
| ADRs | [`decisions/`](decisions/) | Normative architecture decisions. |
|
|
301
|
+
| Embedded spec data | [`src/ptsip/specdata/`](src/ptsip/specdata/) | Tool-packaged schema/registry copies. |
|
|
302
|
+
| Reference Tool | [`src/ptsip/`](src/ptsip/) | Installable Python implementation. |
|
|
303
|
+
| Tests | [`tests/`](tests/) | Tool and contract verification. |
|
|
304
|
+
| Release notes | [`releasenote/`](releasenote/) | Tool/Specification release history. |
|
|
305
|
+
|
|
306
|
+
## Key Specification documents
|
|
307
|
+
|
|
308
|
+
- [`spec/PTSIP-SPEC.md`](spec/PTSIP-SPEC.md)
|
|
309
|
+
- [`spec/PTSIP-CONFORMANCE.md`](spec/PTSIP-CONFORMANCE.md)
|
|
310
|
+
- [`spec/PTSIP-TERMINOLOGY.md`](spec/PTSIP-TERMINOLOGY.md)
|
|
311
|
+
- [`schemas/ptsip-profile.schema.json`](schemas/ptsip-profile.schema.json)
|
|
312
|
+
- [`registry/ptsip-registry.yaml`](registry/ptsip-registry.yaml)
|
|
313
|
+
- [`decisions/ADR-0005-activate-spec-0.3.4-draft.md`](decisions/ADR-0005-activate-spec-0.3.4-draft.md)
|
|
314
|
+
|
|
315
|
+
## Release namespaces
|
|
316
|
+
|
|
317
|
+
Tool releases use `tool-v*` tags. Specification releases/design records use the separate `spec-v*` namespace.
|
|
318
|
+
|
|
319
|
+
The exact normative identity of a mutable draft remains the immutable revision, not the tag string alone.
|
|
320
|
+
|
|
321
|
+
## Maturity
|
|
322
|
+
|
|
323
|
+
PTSIP is a draft project-defined specification, not an ISO, IEEE, IETF, CNCF, or other external industry standard.
|
|
324
|
+
|
|
325
|
+
## License
|
|
326
|
+
|
|
327
|
+
This repository, including the PTSIP Specification and Reference Tool unless explicitly stated otherwise, is licensed under the Apache License, Version 2.0. See [`LICENSE`](LICENSE).
|
ptsip-0.3.4/README.md
ADDED
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
<p align="right">
|
|
2
|
+
English | <a href="README.ko.md">한국어</a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
# PTSIP — Product–Toolchain SDK Isolation Policy
|
|
6
|
+
|
|
7
|
+
**Status:** Draft project-defined specification
|
|
8
|
+
**Specification family:** `0.3.4-draft`
|
|
9
|
+
**Active normative snapshot:** `b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e`<br>
|
|
10
|
+
**License:** Apache License 2.0
|
|
11
|
+
|
|
12
|
+
PTSIP is an architecture policy for keeping Product SDK responsibility separate from development Toolchain SDK responsibility while preserving explicit contracts, reproducible conformance, and multi-environment architecture-decision consistency.
|
|
13
|
+
|
|
14
|
+
> **Purpose precedes reuse.** Classify a component by why it exists and which lifecycle owns it before considering code sharing.
|
|
15
|
+
|
|
16
|
+
## Architecture model
|
|
17
|
+
|
|
18
|
+
PTSIP has exactly three architectural classifications:
|
|
19
|
+
|
|
20
|
+
| Classification | Meaning |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| `PRODUCT` | Product-owned runtime/library/SDK/component responsibility. |
|
|
23
|
+
| `TOOLCHAIN` | Development-tooling-owned SDK/component responsibility. |
|
|
24
|
+
| `NEUTRAL_CONTRACT` | Deliberately non-executable, independently governed contract responsibility. |
|
|
25
|
+
|
|
26
|
+
`UNKNOWN`, `CONFLICT`, `INCOMPLETE`, `PENDING`, and similar states are workflow/evaluation states, not additional architecture planes.
|
|
27
|
+
|
|
28
|
+
The core boundary is:
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
Toolchain SDK ---> Product source / artifacts
|
|
32
|
+
inspect / validate / generate / migrate / package
|
|
33
|
+
|
|
34
|
+
Product SDK -X-> Toolchain implementation
|
|
35
|
+
runtime / shipped dependency prohibited
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Shared semantics should prefer a Neutral Contract over one project-local executable package owned by both planes.
|
|
39
|
+
|
|
40
|
+
## Install and use
|
|
41
|
+
|
|
42
|
+
PTSIP requires Python 3.11 or newer.
|
|
43
|
+
|
|
44
|
+
```powershell
|
|
45
|
+
pip install PTSIP
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Common commands:
|
|
49
|
+
|
|
50
|
+
```powershell
|
|
51
|
+
ptsip --version
|
|
52
|
+
ptsip spec
|
|
53
|
+
ptsip doctor .
|
|
54
|
+
ptsip inspect .
|
|
55
|
+
ptsip pilot .
|
|
56
|
+
ptsip adopt --help
|
|
57
|
+
ptsip validate .
|
|
58
|
+
ptsip clarify .
|
|
59
|
+
ptsip gate .
|
|
60
|
+
ptsip resolve --help
|
|
61
|
+
ptsip conform .
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
For source development:
|
|
65
|
+
|
|
66
|
+
```powershell
|
|
67
|
+
pip install -e ".[dev]"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Specification and Tool lifecycle
|
|
71
|
+
|
|
72
|
+
The **PTSIP Specification** and **PTSIP Reference Tool** are independently versioned.
|
|
73
|
+
|
|
74
|
+
- `pyproject.toml` owns Tool/package source version;
|
|
75
|
+
- `ptsip --version` reports installed Tool version;
|
|
76
|
+
- `ptsip spec` reports the exact Specification family + immutable revision bound to that Tool;
|
|
77
|
+
- `spec/`, `schemas/`, and `registry/` contain canonical Specification assets;
|
|
78
|
+
- `src/ptsip/specdata/` contains matching embedded resources used by the Tool;
|
|
79
|
+
- GitHub Releases publish Tool and Specification release/design records.
|
|
80
|
+
|
|
81
|
+
The existing `spec-v0.3.4-draft` GitHub Release records the earlier design proposal. It remains an immutable historical checkpoint and is not moved. The active repository-identity-migration snapshot is `0.3.4-draft @ b5b17dd16667cc1afaf1d23054b6e5dd773e3f5e`.
|
|
82
|
+
|
|
83
|
+
A Tool version number matching a Specification family number does not imply identity by itself.
|
|
84
|
+
|
|
85
|
+
## Consumer Repository non-intrusion
|
|
86
|
+
|
|
87
|
+
PTSIP does not require adopting repositories to create PTSIP-specific `docs/`, `tools/`, `.ptsip/`, cache, report, or hidden directories.
|
|
88
|
+
|
|
89
|
+
External inspection/Pilot tooling is read-only by default. Tool-owned operational state belongs outside the Consumer Repository unless the user explicitly chooses a repository path.
|
|
90
|
+
|
|
91
|
+
The default project-owned architecture declaration is repository-root `ptsip.yaml`; projects may consistently select another path with `--profile`.
|
|
92
|
+
|
|
93
|
+
Local state such as `control-plane.sqlite3` is not portable architecture authority and must not be Git-shared as repository-global coordination state.
|
|
94
|
+
|
|
95
|
+
## Explicit project adoption
|
|
96
|
+
|
|
97
|
+
Candidate discovery is evidence, not architecture authority. The project owner supplies architecture intent.
|
|
98
|
+
|
|
99
|
+
`0.3.4-draft` defines this structured adoption fact set:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
classification
|
|
103
|
+
purpose
|
|
104
|
+
shipped
|
|
105
|
+
runtime_required
|
|
106
|
+
lifecycle_owner
|
|
107
|
+
executable
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Canonical lifecycle owners are:
|
|
111
|
+
|
|
112
|
+
```text
|
|
113
|
+
PRODUCT
|
|
114
|
+
DEVELOPMENT_TOOLING
|
|
115
|
+
INDEPENDENT
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Example dry-run:
|
|
119
|
+
|
|
120
|
+
```powershell
|
|
121
|
+
ptsip adopt . `
|
|
122
|
+
--component tools `
|
|
123
|
+
--classification TOOLCHAIN `
|
|
124
|
+
--purpose "Repository-local generation tooling" `
|
|
125
|
+
--shipped no `
|
|
126
|
+
--runtime-required no `
|
|
127
|
+
--lifecycle-owner DEVELOPMENT_TOOLING `
|
|
128
|
+
--executable yes `
|
|
129
|
+
--json
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Apply only after reviewing the plan:
|
|
133
|
+
|
|
134
|
+
```powershell
|
|
135
|
+
ptsip adopt . `
|
|
136
|
+
--component tools `
|
|
137
|
+
--classification TOOLCHAIN `
|
|
138
|
+
--purpose "Repository-local generation tooling" `
|
|
139
|
+
--shipped no `
|
|
140
|
+
--runtime-required no `
|
|
141
|
+
--lifecycle-owner DEVELOPMENT_TOOLING `
|
|
142
|
+
--executable yes `
|
|
143
|
+
--apply `
|
|
144
|
+
--json
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Structured adoption preserves those facts losslessly in component declarations. `runtime_required` is not discarded, and canonical `lifecycle_owner` is not aliased to `release_owner`.
|
|
148
|
+
|
|
149
|
+
Boundary-root shorthand remains available for simple declarations, but a write-enabled structured adoption/resolution must refuse mutation when shorthand cannot preserve the full fact set.
|
|
150
|
+
|
|
151
|
+
## Decision Authority
|
|
152
|
+
|
|
153
|
+
PTSIP distinguishes:
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
Specification
|
|
157
|
+
-> normative architecture / conformance / coordination rules
|
|
158
|
+
|
|
159
|
+
Decision Authority
|
|
160
|
+
-> which explicit architecture answer won
|
|
161
|
+
|
|
162
|
+
Project Profile
|
|
163
|
+
-> durable project-owned architecture declaration
|
|
164
|
+
|
|
165
|
+
Observed evidence
|
|
166
|
+
-> what repository/artifacts actually do
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
A Decision Authority is not a conformance oracle and does not replace `ptsip.yaml`.
|
|
170
|
+
|
|
171
|
+
## GitHub-coordinated Reference Tool profile
|
|
172
|
+
|
|
173
|
+
Reference Tool `0.3.4` demonstrates distributed coordination through a dedicated Git ref:
|
|
174
|
+
|
|
175
|
+
```text
|
|
176
|
+
refs/heads/ptsip-policy
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
GitHub storage details are implementation-specific. The Specification requires the semantics, not GitHub itself:
|
|
180
|
+
|
|
181
|
+
- stable coordination-domain + component-scope decision identity;
|
|
182
|
+
- first-valid-resolution-wins;
|
|
183
|
+
- ordered conditional mutation / stale-writer protection;
|
|
184
|
+
- authority freshness at architecture-sensitive boundaries;
|
|
185
|
+
- non-mutating absence lookup;
|
|
186
|
+
- deterministic reconciliation;
|
|
187
|
+
- fail-closed distributed behavior; and
|
|
188
|
+
- separation of global decision state from clone-local application state.
|
|
189
|
+
|
|
190
|
+
## Coding-agent decision gate
|
|
191
|
+
|
|
192
|
+
```powershell
|
|
193
|
+
ptsip gate . --component tools --json
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
In distributed mode, a complete local profile does **not** automatically bypass the authority check. The relevant local declaration is compared with current authority state.
|
|
197
|
+
|
|
198
|
+
| Local Project Profile | Distributed Authority | Required result |
|
|
199
|
+
| --- | --- | --- |
|
|
200
|
+
| declaration absent | no decision | pending only when the active operation actually needs a decision |
|
|
201
|
+
| declaration absent | resolved winner | validate and safely project winner locally |
|
|
202
|
+
| declaration present | no authority decision | use project declaration; do not fabricate authority history |
|
|
203
|
+
| declaration present + equivalent | resolved equivalent winner | resolved/consistent; no formatting rewrite required |
|
|
204
|
+
| declaration present + conflicting | resolved different winner | explicit authority/profile conflict; no silent overwrite |
|
|
205
|
+
| repository/profile changed during reconciliation | any authority state | stale; refuse application and re-analyze |
|
|
206
|
+
|
|
207
|
+
Semantic equivalence means architecture meaning, not YAML key order or whitespace.
|
|
208
|
+
|
|
209
|
+
If distributed coordination is selected but required freshness/safe mutation cannot be established, PTSIP fails the affected operation instead of silently creating a separate Local winner.
|
|
210
|
+
|
|
211
|
+
## Global decision state versus local projection
|
|
212
|
+
|
|
213
|
+
```text
|
|
214
|
+
GLOBAL
|
|
215
|
+
PENDING / RESOLVED
|
|
216
|
+
|
|
217
|
+
LOCAL CLONE / WORKTREE
|
|
218
|
+
missing / consistent / locally applied / stale / failed
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
A global winner does not mean every clone is already synchronized. A clone-local application receipt cannot change the winner.
|
|
222
|
+
|
|
223
|
+
PTSIP uses **action-time synchronization** rather than continuous polling.
|
|
224
|
+
|
|
225
|
+
## Enforced conformance
|
|
226
|
+
|
|
227
|
+
`ptsip conform` evaluates declaration + observed evidence + Product Artifact/build/lifecycle evidence + snapshot/coverage against Consumer Repository PTSIP rules.
|
|
228
|
+
|
|
229
|
+
Completed outcomes are only:
|
|
230
|
+
|
|
231
|
+
| Exit code | Outcome |
|
|
232
|
+
| --- | --- |
|
|
233
|
+
| `0` | `CONFORMANT` |
|
|
234
|
+
| `5` | `NON_CONFORMANT` |
|
|
235
|
+
| `6` | `INCOMPLETE` |
|
|
236
|
+
|
|
237
|
+
A valid Project Profile does not prove conformance. A resolved Decision Authority winner does not prove conformance. A zero-finding scan does not prove conformance when blocking evidence gaps remain.
|
|
238
|
+
|
|
239
|
+
For Enforced Conformance against a mutable draft, bind the exact immutable Specification revision.
|
|
240
|
+
|
|
241
|
+
## Reference Tool focus
|
|
242
|
+
|
|
243
|
+
The Reference Tool provides:
|
|
244
|
+
|
|
245
|
+
- read-only repository inspection and Pilot evidence;
|
|
246
|
+
- multi-language dependency/artifact evidence;
|
|
247
|
+
- deterministic clarification for missing intent;
|
|
248
|
+
- explicit project-owner adoption;
|
|
249
|
+
- on-demand decision gating and explicit resolution;
|
|
250
|
+
- GitHub-coordinated first-winner authority for multi-environment agents;
|
|
251
|
+
- gate-time authority freshness and reconciliation;
|
|
252
|
+
- fail-closed distributed coordination;
|
|
253
|
+
- local-only DecisionStore mode when intentionally selected;
|
|
254
|
+
- project-profile validation;
|
|
255
|
+
- Product Artifact evidence ingestion;
|
|
256
|
+
- evidence-relative Enforced Conformance and stable diagnostics.
|
|
257
|
+
|
|
258
|
+
## Repository map
|
|
259
|
+
|
|
260
|
+
| Area | Location | Purpose |
|
|
261
|
+
| --- | --- | --- |
|
|
262
|
+
| Normative Specification | [`spec/`](spec/) | Architecture, terminology, and conformance rules. |
|
|
263
|
+
| Machine-readable registry | [`registry/`](registry/) | Canonical terms/rule IDs/metadata. |
|
|
264
|
+
| Schemas | [`schemas/`](schemas/) | Project Profile and interoperability schemas. |
|
|
265
|
+
| Agent contract | [`agents/AGENT-CONTRACT.md`](agents/AGENT-CONTRACT.md) | Coding-agent operational contract. |
|
|
266
|
+
| Adoption guide | [`adoption/ADOPTION-GUIDE.md`](adoption/ADOPTION-GUIDE.md) | Controlled adoption sequence. |
|
|
267
|
+
| Reference architecture | [`reference/REFERENCE-ARCHITECTURE.md`](reference/REFERENCE-ARCHITECTURE.md) | Informative architecture guidance. |
|
|
268
|
+
| ADRs | [`decisions/`](decisions/) | Normative architecture decisions. |
|
|
269
|
+
| Embedded spec data | [`src/ptsip/specdata/`](src/ptsip/specdata/) | Tool-packaged schema/registry copies. |
|
|
270
|
+
| Reference Tool | [`src/ptsip/`](src/ptsip/) | Installable Python implementation. |
|
|
271
|
+
| Tests | [`tests/`](tests/) | Tool and contract verification. |
|
|
272
|
+
| Release notes | [`releasenote/`](releasenote/) | Tool/Specification release history. |
|
|
273
|
+
|
|
274
|
+
## Key Specification documents
|
|
275
|
+
|
|
276
|
+
- [`spec/PTSIP-SPEC.md`](spec/PTSIP-SPEC.md)
|
|
277
|
+
- [`spec/PTSIP-CONFORMANCE.md`](spec/PTSIP-CONFORMANCE.md)
|
|
278
|
+
- [`spec/PTSIP-TERMINOLOGY.md`](spec/PTSIP-TERMINOLOGY.md)
|
|
279
|
+
- [`schemas/ptsip-profile.schema.json`](schemas/ptsip-profile.schema.json)
|
|
280
|
+
- [`registry/ptsip-registry.yaml`](registry/ptsip-registry.yaml)
|
|
281
|
+
- [`decisions/ADR-0005-activate-spec-0.3.4-draft.md`](decisions/ADR-0005-activate-spec-0.3.4-draft.md)
|
|
282
|
+
|
|
283
|
+
## Release namespaces
|
|
284
|
+
|
|
285
|
+
Tool releases use `tool-v*` tags. Specification releases/design records use the separate `spec-v*` namespace.
|
|
286
|
+
|
|
287
|
+
The exact normative identity of a mutable draft remains the immutable revision, not the tag string alone.
|
|
288
|
+
|
|
289
|
+
## Maturity
|
|
290
|
+
|
|
291
|
+
PTSIP is a draft project-defined specification, not an ISO, IEEE, IETF, CNCF, or other external industry standard.
|
|
292
|
+
|
|
293
|
+
## License
|
|
294
|
+
|
|
295
|
+
This repository, including the PTSIP Specification and Reference Tool unless explicitly stated otherwise, is licensed under the Apache License, Version 2.0. See [`LICENSE`](LICENSE).
|
|
@@ -4,14 +4,17 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "PTSIP"
|
|
7
|
-
version = "0.3.
|
|
7
|
+
version = "0.3.4"
|
|
8
8
|
description = "Reference development tooling for the Product-Toolchain SDK Isolation Policy"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.11"
|
|
11
11
|
license = "Apache-2.0"
|
|
12
12
|
license-files = ["LICENSE"]
|
|
13
13
|
authors = [
|
|
14
|
-
{ name = "
|
|
14
|
+
{ name = "Kinirin" }
|
|
15
|
+
]
|
|
16
|
+
maintainers = [
|
|
17
|
+
{ name = "Kinirin" }
|
|
15
18
|
]
|
|
16
19
|
keywords = ["architecture", "sdk", "toolchain", "governance", "validation", "ptsip"]
|
|
17
20
|
classifiers = [
|
|
@@ -31,9 +34,9 @@ dependencies = [
|
|
|
31
34
|
]
|
|
32
35
|
|
|
33
36
|
[project.urls]
|
|
34
|
-
Homepage = "https://github.com/
|
|
35
|
-
Specification = "https://github.com/
|
|
36
|
-
Issues = "https://github.com/
|
|
37
|
+
Homepage = "https://github.com/Kinirin/PTSIP"
|
|
38
|
+
Specification = "https://github.com/Kinirin/PTSIP"
|
|
39
|
+
Issues = "https://github.com/Kinirin/PTSIP/issues"
|
|
37
40
|
|
|
38
41
|
[project.scripts]
|
|
39
42
|
ptsip = "ptsip.cli:main"
|